Skip to content

fix(init): 🐛 refuse to set up on a Home Assistant core older than 2026.8 - #801

Merged
rhammen merged 1 commit into
mainfrom
fix/799-ha-version-guard
Sep 15, 2026
Merged

rhammen merged 1 commit into
mainfrom
fix/799-ha-version-guard

Conversation

@rhammen

@rhammen rhammen commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

🔍 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:

Error adding entity text.luxtronik_..._timer_dhw_schedule_week for domain text with platform luxtronik2
  ...
  device = dr.async_get(self.hass).async_get_or_create(**device_info)
TypeError: DeviceRegistry.async_get_or_create

Since 2026.08.30 (#779) the four sub-devices are parented with via_device_id, a DeviceInfo key the device registry only accepts from core 2026.8. On an older core every entity on a sub-device fails to add with that bare TypeError, while the heat pump device (no via_device_id) sets up fine — a confusing half-broken state that is hard to recognise from the log.

hacs.json already 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() raises ConfigEntryError (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 both async_migrate_entry and async_setup_entry: guarding migration keeps the entry at a version the fallback release can still load, so a future CONFIG_ENTRY_VERSION bump 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_id shim (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:

  • an old core raises ConfigEntryError from async_setup_entry before connect_and_get_coordinator is called
  • an old core raises from async_migrate_entry before the entry is touched (async_update_entry not called)
  • the minimum core sets up normally
  • hacs.json's homeassistant equals MIN_HA_VERSION, so the two can't drift

Test values derive from the constant, so a future bump is a one-line change. MAJOR_VERSION/MINOR_VERSION are plain ints on release, beta and dev cores (only PATCH_VERSION is a string), so the tuple comparison is safe for 2026.8.0b1 and 2027.1.

Full run: ruff check + format clean, basedpyright 0 errors, codespell clean, 1272 passed, 1 skipped, coverage 100% (unchanged).

🤖 Generated with Claude Code

- 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
rhammen force-pushed the fix/799-ha-version-guard branch from 0f2a94c to 0dcff16 Compare September 15, 2026 21:22
@github-actions

Copy link
Copy Markdown
Contributor

Code Coverage

Package Line Rate Health
custom_components.luxtronik2 100% ✔
Summary 100% (3787 / 3787) ✔

@rhammen
rhammen merged commit ac3e372 into main Sep 15, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant