Check the entity inside Home Assistant first
The HomeKit Bridge exposes supported Home Assistant entities; first verify the entity works in Home Assistant. Open it there, operate it, and watch the state change.
Treat availability as a diagnostic precheck, not a rule about what can ever be exposed.
If it fails inside Home Assistant, stop there: the bridge cannot repair an entity Home Assistant cannot control. If it works, the fault is in the exposure path: the bridge, the local network, or the Apple side.
The four failure cases at a glance
What you see | What it points to | Check next |
|---|---|---|
No bridge to add in the Home app | Discovery or the pairing surface | Local network, running bridge, current port and name |
Bridge found, but pairing fails or hangs | Pairing state or one bad entity | Pairing code state, log, then the filter |
All bridged accessories show No Response | Bridge transport or the Home hub | Logged interface, port, local path |
One entity missing or never updating | Filter or unsupported domain | Filter, supported domains, accessory count |
Read each row as a separate path; mixing them resets pairings unnecessarily.
Work the documented order
Put the Apple device on the same local network
The official HomeKit Bridge documentation says the iOS device must be on the same local network as Home Assistant. A phone on cellular, a guest network, or another VLAN can fail discovery before any setting matters.
Read the address line in the log
That section says to search the log for Starting accessory Home Assistant Bridge on address and confirm which interface is used. If not, the page documents ip_address.
A web UI that loads proves HTTP works, not local discovery or accessory transport.
Check the bridge identity
Each HomeKit Bridge instance needs its own port — 21063 is the documented default, and multiple instances need different values — plus a unique name on the same local network, 3 to 25 characters.
With more than one bridge, confirm which one you are pairing; a missing accessory may belong to the other.
Count accessories and review the filter
The HomeKit Accessory Protocol allows at most 150 unique accessories per bridge, so the documentation advises filters and splitting large installs.
Filters also explain single-entity problems: only supported domains can be exposed, and the filter decides what is included. Check both before blaming the pairing.
Match the configuration origin
A bridge created in the UI must be configured in the UI only, and a YAML bridge must be edited in YAML. Adding YAML next to a UI bridge creates another instance on a different port instead of changing the first, which explains many "the bridge runs but my change does nothing" reports.
Keep protocol background separate
If you arrived from a Zigbee vs Matter comparison, keep the two questions apart. That guide compares Zigbee's wireless mesh with Matter's application-layer interoperability standard, which can use Thread, Wi-Fi or Ethernet. HomeKit Bridge is a separate integration for exposing existing Home Assistant entities to Apple Home. Zigbee, Matter, Thread and this bridge are not synonyms.
What not to change first
Avoid broad router-wide changes. The documentation mentions IGMP settings and notes that defaults typically work best, so any such change belongs after the log line and port, as a narrow local rule you can undo.
External exposure is worse than a first move. The firewall notes and your deployment instructions describe the local traffic an instance needs; the port is whatever your bridge advertises, not a figure copied from another setup. Follow the current official instructions for your firewall or router model, keep any rule local, and never forward the port to the internet or switch off security wholesale.
Docker and virtualized installs have documented network requirements, including host networking for the documented Docker setup. Those settings change security and platform behavior, so follow your platform's deployment documentation rather than pasting a compose file from a thread; for Docker network isolation, the page documents advertise_ip with an mDNS forwarder.
Defer destructive options too. Deleting .storage, erasing Home app data, or unpairing everything discards names, rooms, scenes, and automations.
If pairing still fails, isolate before resetting
The documented path moves from logs to a temporary minimal configuration that tests whether one entity breaks pairing, then adds entities back. Do it only with a backup: the accessory can behave like a first-time setup, so names, rooms, scenes, and automations may need restoring. The demo.entity-style IDs on the page are documentation examples, not a working configuration.
The integration also documents reset, which returns an accessory to its first-time state, and unpair actions; both belong after evidence. Change one thing, restart, and repeat the test; a brief recovery after a reboot does not prove cause.
Record the evidence before you ask
Fill this in before posting. Leave a cell blank until you have a real observation.
Field | Your value |
|---|---|
Home Assistant version and install type |
|
Apple OS version and device |
|
Symptom stage: missing bridge, pairing failure, all accessories, one entity |
|
Does the entity work in Home Assistant? |
|
Bridge configuration origin: UI or YAML |
|
Local network, interface, and actual port |
|
Sanitized log excerpt |
|
One change made |
|
Result after restart and repeat test |
|
Redact pairing codes, credentials, and precise network details before posting, and never paste a full debug dump.
The other direction is HomeKit Device
The HomeKit Device documentation covers the reverse integration: bringing HomeKit accessories into Home Assistant. It says not to confuse it with HomeKit Bridge, which exposes Home Assistant devices to HomeKit.
A HomeKit device pairs with only one controller at a time, and removing it from the Apple Home app is part of that documented flow. Do not unpair real devices because the bridge is not found; the wrong integration can mimic a missing bridge.
The shortest correct path
Confirm the entity, pick the matching failure case, then check the network, logged interface, port and name, filter, and configuration origin. Only then touch router settings, host networking, or pairing resets.
