Six causes look like one symptom, and only one of them is the bridge

A Matter bridge sits at the boundary between your Home Assistant entities and an external Matter controller. Five things underneath it each have their own lifecycle: the Home Assistant connection, the bridge process, the Matter fabric, the controller session, and the individual device endpoints. When a controller shows No Response, all that tells you is that it cannot reliably reach some Matter endpoint right now. The cause could be a dropped Home Assistant WebSocket, a bridge that is stopped or failed, a fabric that was never commissioned, a controller session that has gone quiet, a subscription that has disappeared, mDNS advertising on the wrong interface, or a mapping that failed on the endpoint itself. If you reset every time you see that message, you destroy commissioning identities that were still valid, and you pay for it in redone rooms, names and automations.

Stable 2.0.55's Bridges page can Start All, Stop All and Restart All across every bridge, and it can import or export bridge settings; the detail page for one bridge shows status, a commissioning summary, failed entities, Entity Mapping, endpoints and clusters. Separately, Health & Diagnostics and Network Map are the pages that let you see which of the five layers above is actually broken before you act. Pick the smallest blast radius every time: check the mapping and the failure reason before restarting a bridge; restart one bridge before you restart all of them; read Health before you conclude the bridge itself is at fault.

Three datasets on the bridge side, three layers on the health side

Settings, identity, and the tree built from both

Bridge settings define the name, port, filter, feature flags, basic identification and priority. Matter identity storage holds the identity data that commissioned fabrics depend on. The endpoint tree is the Matter device tree the bridge builds at start from the current Home Assistant registry, the filter and Entity Mapping. Those are three different sets of data. Exporting the bridge JSON is not a full backup of the identity, and it does not guarantee that a restore avoids re-commissioning.

Start builds the bridge and its endpoints from the persisted settings. Stop shuts down Matter operation for that bridge, which is not the same as deleting its settings. Restart stops it and then starts it again in order. The v2.0.55 frontend has no Refresh Devices button; when the device set or a mapping changes, the normal UI path is to edit, then Restart that one bridge. The backend does have an authenticated POST /api/matter/bridges/:bridgeId/actions/refresh, but that is not a button on the page, and it is not the periodic refresh of the display either.

stateDiagram-v2
  direction LR
  state "Stopped" as S
  state "Running" as R
  state "Failed" as F
  [*] --> S
  S --> R: Start
  R --> S: Stop
  R --> F: a fault occurs
  F --> R: Restart, once cleared

Force Sync runs only when the bridge is running and autoForceSync is enabled; otherwise it reports zero synced. It walks the endpoints and pushes only the state that has changed relative to the in-memory last-sync snapshot — under memory pressure the code can skip the sync entirely.

The device tree on the bridge detail page shows parts downward from the root endpoint, usually an aggregator. Each endpoint card under it shows the device type, the source Home Assistant entity, the Matter clusters and, once expanded, the cluster state. A cluster is a set of capabilities, not a guarantee about the controller UI: even when a cluster is present in the tree, a controller may not show it, may show only some of its attributes, or may behave differently because of product maturity.

flowchart TD
  A["Bridge settings exist"] --> B["Bridge is Running"]
  B --> C["Endpoint exists in the device tree"]
  C --> D["Expected cluster is present"]
  D --> E["Session and subscription are active"]
  E --> F["Controller UI shows it"]

Fabric, session and subscription

A fabric is a trust relationship. A session is a secure connection over a period of time. A subscription is the controller asking the bridge to report certain data on its own. A fabric that exists with zero sessions may mean the controller hub is temporarily offline or the network cannot reach it. A session with zero subscriptions may mean you can read and write but get no continuous state reporting. Sessions and subscriptions both present while one endpoint has failed points at the mapping and the source entity first, not at the network.

The backend's basic Health rolls the HA connection and the bridge counts into healthy, degraded or unhealthy. It is healthy only when HA is connected and no bridge is stopped or failed. It is degraded when HA is connected but a bridge is stopped or failed. It is unhealthy when HA is not connected. This is a service-level summary: it does not mean every entity is fine, and it does not mean every controller supports everything.

flowchart TD
  A{"Is Home Assistant connected?"} -->|"no"| U["Unhealthy"]
  A -->|"yes"| B{"Is any bridge Stopped or Failed?"}
  B -->|"yes"| D["Degraded"]
  B -->|"no"| H["Healthy"]

Detailed Health gives you, for every bridge, its status and reason, port, priority, device count, fabric count, failed entity count, controller warnings and entity diagnostics, plus a session and subscription summary. Subscriptions are split further into whole-node wildcard, endpoint-specific and unknown scope. Seeing that a session exists is still not proof that control works.

Stable, experimental and “no route” are three different claims

Every page named in this part is reachable in Stable 2.0.55, and start/stop, Force Sync, import preview, startup priority, the device tree, mapping profiles, Health, Network Map and Export Diagnostic are all features of that same code. That only tells you the release channel is Stable. It does not mean every device type exposed through a bridge is mature, and it does not mean every controller supports every cluster.

Bridge operations features

Health and diagnostics features

An important version fact: DiagnosticsPage.tsx is present in the v2.0.55 code, and the Health page reuses the LiveEventLog component from it, but routes.tsx registers no separate DiagnosticsPage route. So you cannot claim there is a separate Diagnostics page in the sidebar, and there is no invented URL to hand out. The entry point you can actually use is the live event area embedded in Health & Diagnostics, together with Export Diagnostic.

Startup priority is only the internal bridge start order. It is not network QoS, it is not Matter fabric priority, and it does not tell a controller which bridge to connect to first. The code sorts by number, lowest first; dragging and saving on the Startup Order page writes spaced-out numbers in the order shown on screen. Work from the on-screen order — you do not need to calculate the numbers yourself.

Network Map draws its graph from the bridge and device APIs. It is not a packet capture and not the physical topology your router sees. The controller vendor groups on the graph are built and de-duplicated from the rootVendorId of the commissioned fabric records, so several fabrics from the same vendor merge into one node. Node and edge counts are therefore not an exact fabric count and not a one-to-one topology; for exact fabric records, read Detailed Health instead.

flowchart TD
  F1["Fabric record 1
Vendor A"] --> V1["Vendor node: Vendor A"]
  F2["Fabric record 2
Vendor A"] --> V1
  F3["Fabric record 3
Vendor B"] --> V2["Vendor node: Vendor B"]

Six steps, smallest scope first

1. Step 1

   Record a baseline on Bridges

   Open Bridges and note the target bridge's name, its Running / Stopped / Failed status, its device count, and whether only one bridge is affected. If it is Failed, open the detail page first and copy down a generalized status reason; strip identity, network and secret data before you share those notes.

2. Step 2

   Narrow it down to one bridge

   Select the target bridge, expand failed entities, and read the source entity and the reason for each one. Then work down through Entity Mapping and the endpoint tree: check whether the device is there, whether the Matter device type makes sense, and whether the cluster you expect is present. Fix the Home Assistant unavailable state, the filter exclusion or the mapping setting first — do not use a bulk restart to cover the cause.

3. Step 3

   Pick the smallest lifecycle action

   If you are only stopping for maintenance, use Stop; once you have cleared the cause of a Failed state, use Restart; after adding or removing entities or mappings, restart that one bridge so the endpoint set is rebuilt; only when the bridge is running, autoForceSync is already on, and the endpoints and session are healthy but the controller state is still stale should you run Force Sync from the more menu. Wait for health and the log to settle before the next step.

4. Step 4

   Use the bulk buttons only for whole-batch maintenance

   Go back to Bridges, confirm the maintenance window and that every controller may go offline briefly, then use Start All, Stop All or Restart All. The screen reports how many were processed, but a success notification does not replace checking each bridge; once the batch finishes, confirm the status and the failed entity count one bridge at a time.

5. Step 5

   Set the startup order for the next restart

   Open Startup Order and drag the standard bridges that have fewer dependencies, are smaller, or matter most to the front; put endpoint-heavy or experimental workloads at the back. When the unsaved-changes prompt appears, press Save Changes; the action below it is Save Startup Order. Leave the page only after the unsaved prompt has gone. This saves the priority; it does not restart the bridges there and then.

6. Step 6

   Leave artifacts you can roll back to

   On Bridges, choose Export All to download the settings JSON; if you are moving only part of it, keep the artifact from the per-bridge export API or UI instead. Separately, create a full backup that includes the identity in Settings, and protect it offline. Record the version, the export date, the number of bridges, the mapping maintenance and the intended controllers — and never put a pairing code or a credential in the file.

flowchart TD
  A["You press Force Sync"] --> B{"Is the bridge Running?"}
  B -->|"no"| Z1["Reports zero synced"]
  B -->|"yes"| C{"Is autoForceSync enabled?"}
  C -->|"no"| Z2["Reports zero synced"]
  C -->|"yes"| D{"Has this endpoint changed since
the last in-memory snapshot?"}
  D -->|"no"| Z3["Skipped for that endpoint, normal"]
  D -->|"yes"| Z4["Pushed to the controller"]

Six steps, widest view first

1. Step 1

   Open Health & Diagnostics and read the global summary first

   Check the version, uptime, Home Assistant connected, and the running / total bridge ratio. Do not press Restart first. If HA is disconnected, deal with the shared upstream problem. If only one bridge has failed, narrow down to that bridge.

2. Step 2

   Expand bridge and fabric health one bridge at a time

   Compare the device count, fabric count, failed entity count and controller warnings. Then read the session and subscription summary for each fabric. Record only “present or absent, recent or stalled, and the trend in the counts”; never copy fabric or node identity values into a record you will share.

3. Step 3

   Build a timeline with the Live Event Log

   Keep the event types you need: state update, command received, entity error / warning, session opened / closed, subscription changed, bridge started / stopped. Use the filter chips to isolate the symptom, and reproduce one low-risk action first. Clear Events only clears the list you are watching in the frontend; it is not a fix.

4. Step 4

   Run Network Diagnostics

   Read the pass / warn / fail results and the recommendations, then expand the interface table. Confirm the bound interface is a reachable LAN interface, the IPv4 switch matches your deployment, and IPv6 is present and does not rely only on a link-local address that cannot cross subnets. Do not paste the real addresses on screen into a ticket.

5. Step 5

   Switch to Network Map and cross-check

   Confirm the Hub-to-bridge links, the controller vendor groups built and de-duplicated by rootVendorId, and the Device nodes all match what you expect; for individual fabric records, go back to Detailed Health. Press Refresh Data to reload. Dragging a node only changes the layout held in the browser's local storage; Undo takes back one move, Reset Layout clears the saved positions, and Fullscreen only changes the view.

6. Step 6

   Export a diagnostic or change settings only at the end

   If you still cannot pin it down, press Export Diagnostic, then read the file offline and redact every identity, network address, entity name and secret fragment inside the error text. When you need to change mDNS, the firewall or a VLAN, that is a separate network-and-security pass. When you need to restart or reset a bridge, go back to the operations pass above.

Everything you maintain by hand, and what it does not cover

Importing and exporting bridge settings

The Export All artifact is versioned JSON containing an array of bridge settings and the export time. Import goes through Preview first, listing the name, the port, the number of filter rules and whether the bridge already exists, and letting you choose which bridges to take and whether to overwrite. An older format can be marked for migration in the preview. The safe approach is to preview, tick only what you need, leave overwrite off by default, and apply only once you have confirmed there is no port conflict in the target environment.

A settings export does not include the Matter identity, the entity mappings, bridge image assets or every application setting, so it is good for copying bridge definitions and is not a disaster-recovery file. Keeping the bridge identification fields on import can affect how existing data lines up; never start the same settings on two hosts at once, so that you avoid duplicate service names and identity conflicts.

Bridge icons and device images

A bridge icon lives in a dedicated storage directory, supports the common raster and vector formats, and is capped by a backend file-size limit; a Startup Order card shows a custom icon when it finds one, and otherwise picks a default icon based on the bridge settings. Device images are maintained per Home Assistant entity: the Devices page and the endpoint cards can resolve in bulk whether a custom or automatic source exists, and you can upload and remove them. Images are assets of the admin interface — they do not change the icon on the controller side; the controller still renders from the Matter device type.

Mapping profiles

The Entity Mapping section on the bridge detail page can export a mapping profile, preview an import and apply it. A profile is a good way to move the mapping rules for the same device model to another bridge, but before you import, check that the target entities exist, that the device capabilities are the same, and whether existing mappings would be overwritten. A profile does not contain fabric identity, and it is not a replacement for the bridge filter.

Endpoints, clusters and failed entities

An endpoint card brings the source entity, the device type, the clusters, the cluster state and the automatic-mapping clues together in one place. Read the reason on failed entities first, then compare it with the endpoint tree: if the source entity is not in the tree at all, check the filter, disabled mappings and the HA registry; if the endpoint is there but a capability is missing, check the device class, the overrides and composed entities; if the cluster is there but the controller does not show it, check controller support, and do not switch to a device type that does not match.

Network Map interactions

Network Map supports zoom, pan, the MiniMap, Controls, node dragging, single-step Undo, Reset Layout, Refresh Data and Fullscreen. The positions you drag are saved in the current browser's local storage; they do not survive a different browser, clearing site data, or Reset Layout. Refresh Data fetches the bridges again and then loads the devices for each bridge. It does not perform a Matter factory reset, and it does not repair failed entities.

The system log and Live Event

The system log is where you read startup, mDNS, the HA connection, bridge failures, plugin problems and resource warnings. Live Event leans toward the runtime ordering of state, commands, sessions and subscriptions. Line the two up: mark the time of the symptom first, then read the neighboring events and log lines. Protocol debug can include per-packet information, so turn it on only temporarily, protect it strictly, and put the level back when you are done.

Metrics and System Information

The metrics JSON contains uptime, heap and RSS, bridge total / running / stopped / failed, device and fabric totals, HA connected, and the registry counts; the Prometheus format also carries a status and device count label for each bridge. System Information shows the version and the runtime environment, which is what you cross-check the architecture, the Node version and the resources against. Watch the trend when you monitor; do not read a single spike as a leak.

Translation Editor

The Translation Editor lets you pick a language, search keys, filter by missing or edited, edit local overrides, reset one key at a time, reset all, copy or export JSON, import JSON, and create and remove a custom language. Overrides and custom languages are restored from the browser's local storage. They affect the Matter Hub UI in this browser: they do not change Home Assistant's translations, and they are never pushed to a controller.

Before you import a translation, confirm the JSON holds only string keys and values, with no description of your environment and no secrets. Reset on a key returns it to the built-in string; Reset All clears the local edits for that language. If you delete a custom language, that browser no longer offers it. To move one between browsers, Export JSON first, Import it on the target, and keep a copy you can roll back to.

Four situations, and where each one is answered

At home: the living-room lighting bridge is fine and only one cover endpoint has failed. Read the reason on failed entities, go back to Home Assistant to check the source entity, then fix the mapping. Every other bridge and controller keeps running; restart only that one bridge after the fix, so the whole house does not go offline at the same time.

In a small office: lighting, climate and locks are split across three bridges. When the host restarts, let the small, critical lighting bridge start first, then climate, and leave the endpoint-heavy, higher-load bridges until last. Startup priority pins that order for you, but the network, the firewall and controller reachability still have to be managed separately.

Version maintenance: run Export All first so you can diff the settings, then create a full identity backup. After the upgrade, start the bridges one at a time: check health, the device count, the fabric count and the failed count, then test state in both directions on one low-risk endpoint. A settings export helps you rebuild a bridge; only a full identity backup can keep the fabrics you have already commissioned.

Diagnostic paths, by scope: if every controller fails at once, start with whether HA is connected and whether every bridge went degraded together; a shared root cause in the bound interface or mDNS hits more often than commissioning each bridge again. If only one controller fails, the fabric is usually still there but its session or subscription has stalled while the others are fine — check that controller's hub and the VLAN and mDNS path first, and do not factory reset the whole bridge. If only one entity fails, the bridge and sessions are healthy and Network Map or the Health entity diagnostic gives a reason — go back to the bridge detail page and fix the HA state, the filter or the mapping.

The failures that actually happen

Bridge operations

Health and diagnostics

Questions people ask

Where to go from here