fix(init): 🐛 refuse to set up on a Home Assistant core older than 2026.8 - #801
Merged
Merged
Conversation
- Raise `ConfigEntryError` from both `async_migrate_entry` and `async_setup_entry` when `(MAJOR_VERSION, MINOR_VERSION)` is below the new `MIN_HA_VERSION` constant, naming the required and running versions and release 2026.08.29 as the fallback - The sub-devices are parented with `via_device_id`, which the device registry only accepts from 2026.8; on an older core it fails deep inside `async_get_or_create` with a bare `TypeError`, so the heat pump device sets up and every heating/DHW/cooling entity goes unavailable - HACS gates downloads on hacs.json, but a manual install or a stale HACS data store still lands the release on an old core - fail loud instead - Guarding migration too keeps the entry at a version the remedy release can still load; a `CONFIG_ENTRY_VERSION` bump is a one-way door - Pin hacs.json's `homeassistant` to `MIN_HA_VERSION` with a test, and soften the README's "HACS will not offer" to "should not" Refs #799 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
rhammen
force-pushed
the
fix/799-ha-version-guard
branch
from
September 15, 2026 21:22
0f2a94c to
0dcff16
Compare
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🔍 What this fixes
#799: a user on Home Assistant core 2026.7.1 updated from 2026.08.29 to 2026.09.14 and almost every heating / DHW / cooling entity went unavailable, with this in the log:
Since 2026.08.30 (#779) the four sub-devices are parented with
via_device_id, aDeviceInfokey the device registry only accepts from core 2026.8. On an older core every entity on a sub-device fails to add with that bareTypeError, while the heat pump device (novia_device_id) sets up fine — a confusing half-broken state that is hard to recognise from the log.hacs.jsonalready declares"homeassistant": "2026.8.0"and the README already documents the minimum, but a manual install — or HACS letting a release through, which has happened elsewhere — still lands the release on an old core. This PR makes that fail loud instead.✨ Changes
const.py—MIN_HA_VERSION: Final[tuple[int, int]] = (2026, 8), the single place the floor lives, with a comment naming the reason (via_device_id).__init__.py—_check_ha_version()raisesConfigEntryError(no retry loop; the reason shows on the integration card) when(MAJOR_VERSION, MINOR_VERSION) < MIN_HA_VERSION. The message names the required version, the running version, and 2026.08.29 as the fallback release. Called from bothasync_migrate_entryandasync_setup_entry: guarding migration keeps the entry at a version the fallback release can still load, so a futureCONFIG_ENTRY_VERSIONbump can't silently break the remedy (a bump is a one-way door — HA refuses to load an entry whose version is newer than the integration's).README.md— "HACS will simply not offer you a newer release" softened to "should not", and the note now describes the new error and the two ways out.Not done on purpose: no dual
via_device/via_device_idshim (rejected in #779 — the legacy branch could never be exercised in CI), no guard in the config flow (a brand-new install on an old core still completes the flow and then fails at setup with the same clear message; rare path, not worth the extra code).🧪 Tests
tests/test_init.py::TestHomeAssistantVersionGuard:ConfigEntryErrorfromasync_setup_entrybeforeconnect_and_get_coordinatoris calledasync_migrate_entrybefore the entry is touched (async_update_entrynot called)hacs.json'shomeassistantequalsMIN_HA_VERSION, so the two can't driftTest values derive from the constant, so a future bump is a one-line change.
MAJOR_VERSION/MINOR_VERSIONare plain ints on release, beta and dev cores (onlyPATCH_VERSIONis a string), so the tuple comparison is safe for2026.8.0b1and2027.1.Full run: ruff check + format clean, basedpyright 0 errors, codespell clean, 1272 passed, 1 skipped, coverage 100% (unchanged).
🤖 Generated with Claude Code