Skip to content

ZaptecBaseEntity sets _attr_available = False on KeyUnavailableError but it has no effect on reported availability #410

Closed

Description

@rhammen

Summary

When an entity's value becomes unavailable, ZaptecBaseEntity._handle_coordinator_update sets self._attr_available = False. However, ZaptecBaseEntity subclasses HA's CoordinatorEntity and never overrides its available property. CoordinatorEntity.available returns self.coordinator.last_update_success and ignores _attr_available entirely, so the flag has no effect on the entity's actual reported availability.

Details

In custom_components/zaptec/entity.py:

def _handle_coordinator_update(self) -> None:
    ...
    try:
        update_from_zaptec()
        ...
    except KeyUnavailableError as exc:
        self._attr_available = False   # <-- set here
        self._log_unavailable(exc)
    super()._handle_coordinator_update()

_attr_available is written (and read by the internal _log_unavailable logging helper), but because available is never overridden, HA continues to report availability based solely on coordinator.last_update_success. An entity whose specific key disappears (while the coordinator refresh itself still succeeds) therefore stays available in HA, contrary to what the _attr_available = False assignment suggests is intended.

Impact

  • Individual entities that lose their backing key are not marked unavailable in the UI as the code appears to intend.
  • The unavailable/available transition logging still works (it reads _attr_available directly), which can make logs and actual entity state disagree.

Possible fixes (for discussion)

  1. Override available on ZaptecBaseEntity to combine super().available with self._attr_available.
  2. Remove the _attr_available assignment if per-key unavailability is intentionally not surfaced, and drive the logging off something else.

Option 1 matches the apparent intent, but needs care since many keys are legitimately absent for some charger/installation types and shouldn't flap to unavailable.

Notes

Surfaced while adding coordinator/entity unit tests (#394); a test there documents the current (unintended) behavior.

Activity

  1. added a commit that references this issue on Jul 25, 2026
  2. rhammen commented on Jul 25, 2026

    @rhammen
    ContributorAuthor

    Some additional findings while designing the test coverage, plus a request for input on the intended semantics.

    A second, latent bug: the flag is never reset

    Beyond available not being overridden, _handle_coordinator_update only ever sets _attr_available = False (on KeyUnavailableError) and never sets it back to True on the success path:

    try:
        update_from_zaptec()
        self._log_value(self._log_attribute)
        self._log_unavailable()
    except KeyUnavailableError as exc:
        self._attr_available = False   # set False here...
        self._log_unavailable(exc)
    super()._handle_coordinator_update()
    # ...but never reset to True on success

    So even if available were wired to read _attr_available, an entity that recovered would stay unavailable forever. Any fix therefore needs to both override available and reset the flag on a successful update — not just the former.

    The design question: should a missing key mark the whole entity unavailable at all?

    This is the part I'd like maintainer input on before implementing. Many Zaptec keys are legitimately absent for certain charger models, installation types, or the authenticated user's role. The code already appears to treat some absences as expected — _log_unavailable carries a skip-set (e.g. three_to_one_phase_switch_current) to suppress error logging for keys that routinely aren't present.

    If we make any KeyUnavailableError flip the entity to unavailable, entities that today quietly remain present could start disappearing for real users. So:

    • Should a missing key drive the entity's available state, or only coordinator success?
    • If it should, which keys are "required" vs. legitimately optional — and how does that interact with the existing skip-set?

    Plan

    I'm keeping the in-progress test-suite work (the pytest-homeassistant-custom-component migration replacing #394/#395) test-only — it will document the current behavior with an xfail referencing this issue rather than change production behavior. The actual fix is best decided here first.

    @sveinse @steinmn — input on the intended availability semantics would be very welcome before I implement anything.

  3. steinmn commented on Jul 25, 2026

    @steinmn
    Contributor

    I think you are missing a few key ingredients here:

    1. update_from_zaptec calls _update_from_zaptec which is defined in each derived entity-class (binary_sensor, number, etc.). In each of these, _attr_available is set to True after a successful update. See for example binary_sensor.py#L30-L34
    2. available is a read-function/cached-property that simply returns self._attr_unavailable, see homeassistant/helpers/entity.py#L871

    If this was an actual bug, I think we would have been getting tons of issue reports about it.

  4. steinmn commented on Jul 25, 2026

    @steinmn
    Contributor

    Another important clarification on HA terminology: Entity and Device are not the same.

    Chargers and Installations are devices. The individual buttons, sensors, number-controllers are entities. So a Device will have multiple entities, and just because one of the entities becomes unavailable does not mean the device becomes unavailable.

  5. rhammen commented on Jul 26, 2026

    @rhammen
    ContributorAuthor

    @steinmn
    You are correct.
    The AI got a bit too enthusiastic, and missed what is defined in the HA class, and I didn't pay enough attention in the process.
    I do understand the differences between devices and entities, I didn't check the actual implementation in HA/this custom component before allowing the AI to post the bug. I will be more careful about this in the future.
    Sorry for this noise.
    Closing this as not-a-bug.

    In the words of the AI:
    ZaptecBaseEntity subclasses CoordinatorEntity, and CoordinatorEntity.available is what actually wins by MRO — not the base Entity.available I originally cited in the report (nor the one linked above, which is also shadowed). CoordinatorEntity.available returns self.coordinator.last_update_success directly and never reads _attr_available:

    def available(self) -> bool:
        """Return if entity is available."""
        return self.coordinator.last_update_success
    

    So the conclusion holds, and more precisely than I first argued: entity availability here is driven by coordinator poll success, by design — not by whether any single key is present. _attr_available being set (and correctly reset by each platform's _update_from_zaptec, e.g. binary_sensor.py) has no effect on reported availability, but that's expected given the base class, not a latent gap.

    What I missed in the original report: I read ZaptecBaseEntity._handle_coordinator_update in isolation and concluded "available is never overridden" — true only in the literal sense that ZaptecBaseEntity itself doesn't add an override. I didn't check that CoordinatorEntity already provides one, and that it's exactly the right one for coordinator-backed entities: a missing key on one attribute shouldn't flip the whole entity unavailable, and (per your second point) an entity going unavailable shouldn't be conflated with its device.

  6. sveinse commented on Jul 26, 2026

    @sveinse
    Collaborator

    @rhammen we have recently merged in an AI policy and AGENTS.md file. Please use this as guidance for the AI agent. If you see that the agent is unable to grasp some of these central concepts/archtecture, please consider adding a description in DEVELOPMENT.md and/or AGENTS.md. The former is perferred, as it also serves humans.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions