[ruaan-deysel]

Pull Request

Description

Fixes #398. unraid-api 1.14.1 (released 2026-10-30, tinkerologie/unraid-api#137) fixes two problems this integration has with Unraid API 4.37.8 and later:

• Stopped services: a stopped Docker or VM service (array stopped, Docker disabled, VM manager off) made 1.14.0 raise AttributeError. The coordinator's optional-service handlers don't catch that, so the whole system poll failed. 1.14.1 raises UnraidAPIError, which _query_optional_containers/_query_optional_vms already handle.
• VM UUIDs: these servers refuse introspection, so 1.14.0 stopped requesting VM UUIDs, and the uuid attribute on VM switches and sensors and in diagnostics went missing. 1.14.1 requests them again.

This PR raises the requirement to unraid-api>=1.14.1 and updates every documented pin; several were stale (1.13.2, 1.6.0).

Type of Change

• Bug fix (non-breaking change fixing an issue)
• New sensor or entity platform
• New feature or enhancement
• Breaking change (change that causes existing automations or setups to fail)
• Documentation update
• Code refactoring (no functional changes)
• Test additions or improvements
• Frontend topology card or UI update

Pre-Submission Governance

• I built and ran the project locally and verified this change actually works (not just that it compiles)
• I ran pytest locally and all tests pass
• I ran ./script/lint locally and it passes
• I pasted real local verification output under Testing Performed below (no placeholder text)
• This PR is self-contained and is not a duplicate; I have not opened other overlapping or back-to-back PRs for the same change
• If an AI agent created or assisted with this PR, a human reviewed and verified the changes before submission

Related Issues

Fixes #398

Critical Rule: Never Bypass unraid-api

• This PR does not bypass unraid-api: no direct GraphQL, HTTP/REST, WebSocket, SSH, or raw socket calls to the Unraid server have been added
• All communication with the Unraid server strictly uses UnraidClient from unraid-api
• If functionality needed for this PR is missing or incomplete in unraid-api, an issue has been filed at https://github.com/tinkerologie/unraid-api and this PR waits for the library to ship it

The fix belongs in the library, as AGENTS.md requires: tinkerologie/unraid-api#135, released as 1.14.1.

Changes Made

• custom_components/unraid/manifest.json, pyproject.toml: unraid-api>=1.14.1.
• uv.lock: uv lock --upgrade-package unraid-api; only unraid-api changed (1.14.0 → 1.14.1).
• Documented pins in AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .github/instructions/api.instructions.md, .github/instructions/manifest.instructions.md and docs/development/ARCHITECTURE.md.
• CHANGELOG Fixed entry.

Home Assistant Quality Scale & Standards

• Verified against the Home Assistant Developer Docs and Quality Scale rules
• Uses entry.runtime_data patterns where applicable (no new hass.data[DOMAIN] usage)
• All entities read from coordinator state (coordinator.data) and avoid direct API/network calls
• New/updated entities use integration base entity classes appropriately
• Sensor implementations use modern native properties (no unit_of_measurement)
• Uses Home Assistant session helpers (no direct aiohttp.ClientSession() instantiation)
• Diagnostics redaction handled when sensitive fields are exposed
• Not applicable (documentation-only or metadata-only change): dependency pin only

Testing Performed

• Ran unit tests (pytest)
• Ran linter (./script/lint)
• Ran type checking (./script/type-check or mypy custom_components/unraid)
• Ran pre-commit checks (pre-commit run --all-files)
• Tested live in local Home Assistant (./script/develop): deployed to the dev Home Assistant 2026.11.0b1
• Not applicable (documentation-only or metadata-only change)

Test Results

$ uv lock --upgrade-package unraid-api
Updated unraid-api v1.14.0 -> v1.14.1
$ pytest                       (HA 2026.10.1, unraid-api 1.14.1 from PyPI)
1456 passed in 15.05s
$ pytest --no-cov              (HA 2026.10.4, unraid-api 1.14.1 from PyPI)
1456 passed in 13.34s

Live, dev Home Assistant core-2026.11.0b1 with Unraid API 4.37.9 (deployed from this branch, restarted):
  in-container unraid-api 1.14.1   (installed by Home Assistant from manifest.json)
  switch.cube_vm_home_assistant_2 uuid=2d7a3a38-f9a6-9acb-bc3c-397b2ad8a644
  switch.cube_vm_fedora           uuid=08e9bfa2-d0e7-fdf2-66e4-c035c04bc7a3   (missing with 1.14.0)
  sensor.cube_docker_total_cpu = 1.02
  error_log "custom_components.unraid": 0 records; system_log "unraid": 0 entries

Documentation

• Code comments added/updated where needed
• README.md updated (if needed)
• CHANGELOG.md updated under [Unreleased]
• AGENTS.md / developer documentation updated (if architecture or process changed)
• No documentation needed

Breaking Changes

None.

Checklist

• I have updated CHANGELOG.md under [Unreleased] with details of this change
• I verified my code against Home Assistant integration quality rules and used no deprecated APIs
• I linked the related issue in Related Issues (only maintainers may note "None", for housekeeping)
• I completed all required sections in this template and removed placeholder-only content
• My code follows the project's coding standards and Home Assistant patterns
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas (if applicable)
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works (if applicable)
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published (if applicable)
• No sensitive information (tokens, passwords, personal data) is included

Disclosure: this PR was written with the help of AI (Claude Code). The "human reviewed" box above is left for the maintainer to tick after review.

Summary by CodeRabbit

• Bug Fixes
  • Fixed an issue where stopped Docker containers or virtual machines could make all system entities unavailable. VM switches, sensors and diagnostics now display VM UUIDs again.
• Requirements
  • Requires Unraid API 1.14.1 or later.

[coderabbitai]

Walkthrough

The package requirements and documented minimums for unraid-api are raised to 1.14.1. The Unreleased changelog describes the reported entity-availability and VM UUID issues on Unraid API 4.37.8 or later, and states that unraid-api 1.14.1 is required.

Possibly related issues

• #398 — Describes the stopped-service and missing-VM-UUID issues addressed by requiring unraid-api 1.14.1.

Possibly related PRs

• tinkerologie/ha-unraid#373 — Raises the same package minimum to 1.14.0, which this change advances to 1.14.1.

Priority: Normal

Severity of issue fixed: Medium

Merge Risk: Minimal · up to c12a9

No actionable merge-blocking risk is evident in these metadata and documentation updates.

Pre-merge checks: 3

Check name	Status	Explanation
Linked Issues check		The changes meet the coding requirements in [#398]. custom_components/unraid/manifest.json and pyproject.toml require unraid-api>=1.14.1. The whole-PR summary reports that uv.lock updates `unr…
Out of Scope Changes check		The changes remain within [#398]. Dependency declarations, the lockfile, documented pins, and the CHANGELOG directly support the requested dependency update and its documented effects. No unrelated pr…
Tests Cover Changed Code		The pull request changes only documentation, changelog text, dependency metadata in manifest.json and pyproject.toml, and the uv.lock dependency lock file. It adds no non-test source functions, …

Full details: Linked Issues check

Explanation

The changes meet the coding requirements in [#398]. custom_components/unraid/manifest.json and pyproject.toml require unraid-api>=1.14.1. The whole-PR summary reports that uv.lock updates unraid-api from 1.14.0 to 1.14.1. The summary also reports updated pins in AGENTS.md, CLAUDE.md, GEMINI.md, the GitHub instruction files, and ARCHITECTURE.md. The CHANGELOG entry records the fix. Reported tests pass with 1,456 tests passing on both runs.

Full details: Out of Scope Changes check

Explanation

The changes remain within [#398]. Dependency declarations, the lockfile, documented pins, and the CHANGELOG directly support the requested dependency update and its documented effects. No unrelated product behaviour or direct Unraid API access was added.

Full details: Tests Cover Changed Code

Explanation

The pull request changes only documentation, changelog text, dependency metadata in manifest.json and pyproject.toml, and the uv.lock dependency lock file. It adds no non-test source functions, branches, or error handling. Tests are not required by this check.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[tinkerologie-bot]

✅ Pull request checklist complete

Everything checks out. Thanks for fixing the earlier problems: this pull request is ready for review.

---

_{📖 Contribution rules · 🔎 Check details}

[greptile-apps]

Confidence Score: 5/5

[Medium impact] This PR appears safe to merge.

Summary

Requires unraid-api>=1.14.1 to consume the stopped-service and VM UUID fixes.

• The integration now keeps polling through stopped services and shows VM UUIDs again.

Acknowledged deferral: ruaan-deysel explicitly leaves the human-review checkbox for the maintainer to complete.

Review checked source code; no tests were run.

_{Reviews (1) · Last reviewed commit: "fix: require unraid-api 1.14.1 for Unrai..." · Reviewed by Greptile}