Bridges, devices and startup management

The goal of operations is not “restart it again”

A Matter bridge is the long-lived boundary between your Home Assistant entities and an external Matter controller. The Home Assistant connection, the bridge process, the Matter fabric, the controller session and the device endpoints each have their own lifecycle; a fault in one layer does not mean the others are broken. If you reset every time you see No Response, you destroy commissioning identities that were still valid and pay for it in redone rooms, names and automations.

The Stable 2.0.55 Bridges page can run Start All, Stop All and Restart All across every bridge, and it can import or export bridge settings; the detail page for a single bridge shows status, a commissioning summary, failed entities, Entity Mapping, endpoints and clusters. The Startup Order page keeps startup priority separate. Pick the smallest blast radius first: if one device displays incorrectly, check the mapping and the failure reason; restart a bridge only when that one bridge is stuck; consider bulk actions only during a shared maintenance window.

The bridge and device lifecycle

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, 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 control; when the device set or a mapping changes, the normal UI path is to edit and 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 same as the periodic refresh of the display. Force Sync runs only when the bridge is running and autoForceSync is enabled; otherwise it reports zero synced. It pushes only the state that has changed relative to the in-memory last-sync snapshot.

The device tree on the bridge detail page shows parts downward from the root endpoint. The usual root node is an aggregator, and 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.

Keep Stable, maturity and controller support separate

The Bridges page, the bridge detail page and Startup Order in this chapter are all routes you can reach in Stable 2.0.55, and bulk start and stop, Force Sync, import preview, startup priority, the device tree, mapping profiles and device images 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.

Startup priority is only the internal bridge start order inside HAMH. 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; when you drag and save on the Startup Order page, it writes spaced-out numbers in the order shown on screen. A bridge with no setting shows the default priority value, so work from the on-screen order — you do not need to calculate the numbers yourself.

One reversible operations pass, start to finish

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. 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. 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. 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. 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, and 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. 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, you can also keep the artifact from the per-bridge export API or UI. 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.

Maintaining imports, icons, mappings and the device tree

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. For the full scope, use Backup as described in Chapter 22. 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.

An operating rhythm for homes and small offices

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.

Symptom, check, safe fix

1. It goes Failed immediately after Start

   Check: the status reason on the detail page, the system logs, whether HA is connected, the port, and storage permissions. Safe fix: clear the obvious cause and restart that one bridge; if it still fails, keep the log and the settings, and do not run a factory reset. Auto Recovery only retries a failed bridge; it cannot fix a configuration error.

2. Force Sync reports zero, very few, or skipped

   Check: whether the bridge is running, whether autoForceSync is enabled, whether the endpoints really have changed relative to the in-memory snapshot, the session and subscription on Health, and memory in metrics. Safe fix: restore the HA and controller connections and reduce resource pressure first, then run it once only; unchanged endpoints being skipped is normal.

3. The import preview says the bridge already exists

   Check: the bridge name, its identification, the port, and the settings already in the target environment. Safe fix: leave overwrite off by default and select only the bridges that are genuinely missing; if you do need to overwrite, take a full backup first and arrange to stop the conflicting bridge.

4. The device exists in Home Assistant but not in the device tree

   Check: Filter Preview, the hidden or disabled state, a disabled mapping, the device class and the failed reason. Safe fix: fix the filter or the mapping and restart that one bridge; do not assign a Matter type that does not match just to make the device appear.

5. The cluster is in the device tree but the controller offers no controls

   Check: that controller's support for the Matter device type and cluster, and how mature the feature is. Safe fix: keep the correct mapping, split the device out to a compatible controller, or use a more conservative type the controller does support; do not claim the controllers are equivalent.

6. Custom icons or images disappear after a restart

   Check: whether the persistent storage is mounted, and whether the assets fall inside the scope of the backup you used. Safe fix: fix persistence, then re-upload from a trusted original; a lost icon is never a reason to reset a fabric.

FAQ

Pinned-version sources

• v2.0.55 source for the Bridges page bulk actions and import / export
• v2.0.55 source for startup priority ordering
• v2.0.55 source for the bridge detail page, failed entities and the endpoint tree
• v2.0.55 source for the Force Sync, Factory Reset and Delete menu
• v2.0.55 Force Sync flag and snapshot conditions, and the Running-only factory reset behavior
• v2.0.55 source for bridge export, preview, migration and import
• v2.0.55 source for mapping profile import and export
• v2.0.55 source for bridge icon storage and format limits