Skip to content

Troubleshooting and Support

barneyonline edited this page Nov 10, 2026 · 9 revisions
HomePod Sensor Link — Troubleshooting and Support

Troubleshooting and support

Discovery shows no devices

Check that HA and the HomePods are reachable on the local network and that your network allows HAP/mDNS traffic between them. Only public HAP discovery results and this integration’s retained setup records appear; native HomeKit entries are never inspected.

HomePods already managed by this integration are hidden from the add-device list. Use Manage existing devices for those devices. If the list is empty, choose Search again or Import pairing export. A failed search has its own error screen. Searching again keeps the current import; importing a new export replaces it.

Some HomePods appear only in AirPlay discovery

AirPlay (_airplay._tcp) and the HomeKit sensor service (_hap._tcp) advertise separately. Seeing a speaker in AirPlay does not supply its HAP endpoint. If HAP multicast browsing is incomplete, use Reconfigure → Import pairing export to find missing devices with an authorised aiohomekit dictionary containing address hints. The integration sends bounded directed HAP DNS-SD queries through temporary unicast UDP reply sockets, reads current ports from fresh replies, and returns to device selection before pairing. Check local connectivity if those queries also fail; exported ports may be stale.

Credential import is refused

Use an HA administrator session on the local network. Credential forms are tied to the administrator who started the setup flow. Start a new flow if that administrator changes. Trusted proxies must preserve the real client address.

Use the credential extraction guide to prepare an export. Selected HAP CSV and the existing pairing JSON formats have a 128 KiB limit. Check for missing keys, mismatched key pairs or conflicting records. A HomeKit setup code cannot replace controller credentials.

Native irestore keychain.json import is implemented on main but is not included in the latest published release, v0.2.0, as of 9 November 2026. Builds containing that feature accept up to 2 MiB of UTF-8 irestore JSON; older builds reject the raw dump. Check the release notes for the build you installed. The manifest version alone does not distinguish an unreleased development checkout from the v0.2.0 release.

Setup is pending after restart

Select Reconfigure → Manage existing devices, choose the HomePod, then choose Resume setup to continue with the saved controller identity. Cancel setup keeps it paused. Review the confirmation before submitting. Ready devices continue independently.

Monitoring has stalled

From v0.2.0, the integration raises a Repairs issue and persistent notification when a monitored device has no completed check for fifteen minutes. Inspect the Sensor access diagnostic's last_completed attribute and status. A changing last_checked value only shows that an attempt started.

Check connectivity and reload the integration if checks remain stalled. The alert clears when checks resume. A completed failed check also clears a stalled-check alert, so investigate the status separately if sensor access is still failing. See monitoring alerts.

Recovery is waiting or blocked

Condition Meaning and next step
Network/discovery failure Restore connectivity; these failures never authorise a pairing change
Startup grace or insufficient confirmed failures Allow the normal five-minute checks to collect evidence
Hourly/daily attempt limit Wait for the rolling window; repeated manual checks do not bypass it
Accepted pairing, sensor publication pending Check measurement availability; persisted publication retries are bounded
Identity/key/permission mismatch Investigate the exact device and imported identity; Resume cannot replace the pin
Competing recovery engine Remove/disable the conflicting helper using its own supported process before using this one

Removing and re-adding the integration deletes saved credentials and recovery history, requiring setup again. Wait for the recovery window instead.

Readings are missing or unchanged

An unchanged numeric value can still be a fresh reading. Inspect last_completed and diagnostic status. Integration-owned measurements become unavailable when their latest sample is more than ten minutes old, setup is incomplete or access is blocked.

Reporting a problem

Record the integration version, HA version, HomePod model/software, whether a device needs a separate connection or is already configured, recovery policy, controlled status/error category and steps to reproduce. Curated integration diagnostics use anonymous device ordinals, but review any attachment yourself before sharing.

Never attach keys, import files, backups, complete HA storage, addresses, controller/device IDs, household names, raw exceptions or unreviewed logs. For security concerns, follow the security reporting guidance.