Downloading a file and being able to restore from it are two different claims

What can actually be recovered from a Matter bridge is: the bridge config, the entity mappings, the Matter identity and fabric credentials, the plugin enabled / disabled state of each bridge, and a handful of administrative assets. That list matters because of what is missing from it once the identity goes. If the identity is lost you can rebuild the bridge settings from a config backup, but every controller that already commissioned this bridge still has to commission it again — the identity is what a controller recognizes, not the settings behind it. And if you ever start that same identity running on two hosts at once, you get duplicate services and mDNS and session behavior that nobody can predict for you in advance.

Settings → Backup & Restore is where all of this lives: downloadable config backups and full backups, a restore preview, per-bridge selection, an overwrite switch, include mappings, restore identity, internal snapshots, auto backup and retention. A restore can overwrite your current settings and ask the application to restart, so the rule before every restore is the same one you will see repeated through this part: take one more backup of the current state first, so you have an explicit way back.

flowchart TD
  A["What are you actually facing?"] --> Q1["Just a mis-edited setting"]
  A --> Q2["The host or the volume failed"]
  A --> Q3["A controller shows No Response"]
  A --> Q4["The identity is confirmed unusable"]
  Q1 --> F1["Selective restore,
identity left alone"]
  Q2 --> F2["Stop the old instance,
then restore in full"]
  Q3 --> F3["Fix the network or restart
that one bridge, no reset"]
  Q4 --> F4["Factory or disaster reset,
the last resort"]

Bridge export, config backup, full backup, snapshot — read the label before you trust it

A bridge export JSON, covered when this guide looked at bridge operations earlier on, mainly holds bridge definitions, and it is what you use to move filters and basic settings around. A config backup ZIP holds the Bridges and entityMappings inside backup.json, and it says so explicitly: it contains no identity. Its archive does carry the per-bridge plugin enabled / disabled flags that exist at the time, but no bridge icon — and after you restore one, you are recommissioning every bridge in it, on purpose.

A full backup ZIP asks for the identity to be included, but it only packs one in for a bridge where that bridge's identity directory actually exists on disk, and it adds the matching bridge icon where it can. On the plugin side you still get nothing more than the enabled / disabled flags. includesIdentity: true in the archive metadata describes the request as a whole — it is not proof that every single bridge inside was packed with its identity intact. A stored snapshot, manual or automatic, uses that same conditional identity-and-icon scope, and retention quietly deletes the older files for you. After any restore, compare identitiesRestored against the number of bridges you actually selected before you decide the identities came through whole.

flowchart TD
  A["Four kinds of export"] --> B["Bridge export JSON:
bridge definitions only"]
  A --> C["Config backup ZIP:
Bridges + entityMappings,
no identity, explicitly"]
  A --> D["Full backup ZIP:
+ identity where the
directory exists,
+ matching bridge icon"]
  A --> E["Stored snapshot:
same conditional scope
as the full backup"]
  B --> Z["Never packed by any of
the four: plugin packages,
installed-plugins.json,
per-plugin config and secrets,
Lock Credentials, device-images,
app settings"]
  C --> Z
  D --> Z
  E --> Z

The code behind these archives simply does not pack every storage asset: installed plugin packages, installed-plugins.json, per-plugin config, storage and secrets, Lock Credentials and device-images all sit outside the backup scope. App-level settings such as Basic Auth, Auto Recovery and the backup preference itself do not appear in the backup.json restore scope either. Keep a separate note of the non-secret settings, keep a trusted original of every asset that is excluded, and put actual secrets nowhere but a dedicated secret manager and an encrypted backup — never in your own operations notes.

What each release channel actually promises

Update Checker compares your current version against the latest release information and shows the release notes and the runtime environment it detected. It does not install anything for you. The actual update method depends on whether you run the add-on, Docker or npm, so “a new version exists” is not the same sentence as “we have upgraded safely” — read the release notes, take a backup, confirm which image or package you can roll back to, and only then update inside a maintenance window.

Auto Backup is on by default with retention set to 5, and it attempts one automatic snapshot at graceful shutdown rather than on any periodic schedule. Auto Recovery is on by default with an interval of 60 seconds, and the UI lets you set anywhere from 10 to 3600. It restarts failed bridges periodically and also triggers a recovery pass after Home Assistant reconnects; a bridge that is already running is left alone. If the actual root cause is a port conflict, a bad setting or not enough memory, Auto Recovery only produces a growing pile of retry records — it will not repair the configuration underneath them.

Seven moves, in an order that keeps you from finding out the hard way

1. Step 1

   Build a backup inventory

   In Settings → Backup & Restore, create a manual snapshot, and download both a config backup and a full backup. Record the version, the date, the number of bridges, the number of mappings, and whether identity and icons were included. Never copy an identity or a secret value into that inventory — note that it exists, not what it is.

2. Step 2

   Move it off the host, and verify it

   Copy the archive to encrypted offline storage, compute a checksum, and confirm the ZIP actually opens and that you can read its README and metadata. Do not unpack the identity into a shared folder to test it, and clear any temporary files once you are done.

3. Step 3

   Create a rollback point before any change

   Before an upgrade, a plugin install, a migration or a restore, take one more full snapshot of the current state. Record the image or package version you are on, the storage mount, and the non-secret settings you would need to rebuild — and confirm the old image is still available to you.

4. Step 4

   Run Restore Preview first

   Upload a trusted archive and check its version, its creation time, whether it includes identity, whether each bridge already exists, and the mapping count. Select only the bridges you actually want restored. Leave overwrite off as it comes by default, and set include mappings and restore identity to match your plan — not the other way around.

5. Step 5

   Stop the conflicting source, then restore

   If you are migrating, stop the old instance first, so exactly one active instance ever holds that identity at a time. Run Restore and read the restored, skipped and errors counts it reports. If the UI asks for a restart, use a graceful restart and wait for Home Assistant and the bridges to settle before you judge anything.

6. Step 6

   Verify identity stability, layer by layer

   Confirm the version, Home Assistant connected, bridges running, the device and fabric counts, failed entities, sessions and subscriptions, and the mDNS interface. Then test one low-risk endpoint in both directions — controller to Home Assistant, and Home Assistant to controller. “The page loads” is not a complete verification on its own.

7. Step 7

   If it fails, roll back — do not overwrite again

   Stop the new instance, keep the redacted logs, and either restore the pre-change snapshot or start the old instance back up. Keep exactly one active instance at all times. If the archive reported errors, do not go on to overwrite more bridges on top of that — work out the version, the storage permissions and the missing files first, then retry only the items that actually failed.

Moving hosts without losing commissioning, and keeping a small host alive

The safe migration order is fixed: full backup, then verify the archive, then stop the old instance, then restore the new instance onto the same storage layout with the complete identity, then start exactly one new instance, then verify. Only when the bridge ID, the identity directory and the endpoint identity all travel together do you have a real chance of controllers not needing to commission again. Copying just the bridge config, or letting the storage volume come up as an empty directory on the new host, will not get you there.

sequenceDiagram
  participant O as Old host
  participant Y as You
  participant N as New host
  Y->>O: take a full backup
  Y->>O: verify the archive, off-host
  Y->>O: stop the old instance
  Y->>N: restore the full backup,
same storage layout
  Y->>N: start exactly one instance
  Y->>N: verify identity, fabric, mDNS

Stable identity and persistent entity identity cut the chance that endpoints get renumbered after a restart, but a large change to the filters, the mappings, or a plugin's device set can still change what a controller sees on the other side. Do not rename things, rewrite filters, switch on Server Mode or jump several versions in the same move — prove the identity survived unchanged first, then change exactly one item at a time.

Keep a separate note of everything the archive leaves out

Track the non-secret settings on your own: whether Basic Auth comes from the environment or from stored settings, Auto Recovery's enabled state and interval, backup auto and retention, the mDNS start options, the base path and the log level. For an actual secret value, write down only that a secret manager supplies it — never the value. Bridge icons do travel in the full backup; device images do not, so keep the original files ready separately, and a local translation override has to be exported from the browser that holds it, since nothing else collects it for you.

When the host itself is the constraint

The official low-resource guidance for this version says Matter Hub loads the Matter cluster definitions, the Home Assistant registry and the V8 engine overhead at startup, and memory then grows with the endpoint count. When resources are tight: shrink the filters first, cut the endpoint count, turn off auto composed where you do not need it, move non-essential large add-ons elsewhere, and watch the heap and RSS trends in your metrics alongside any host-level out-of-memory signals.

Force Sync can be skipped outright under heap pressure, and a process that restarts with no stack trace — where the last thing you see is Killed or a plain container exit — is the classic sign of an out-of-memory kill. On plain Docker or npm you can tune the Node heap by the official guidance; in the add-on, the entrypoint sets that dynamically, so there is no UI option to invent here. Swap is a buffer against a spike, not an answer to an endpoint count that keeps growing.

Three situations that end well, and one that is a last resort by definition

Routine updates: Update Checker only tells you a version exists. Read the release notes, take a full snapshot, keep the image you are currently on, update one environment, and verify it layer by layer as in the steps above. If a schema or controller regression shows up, stop the new version and roll back to the old version and the original snapshot — do not keep resetting things inside the broken environment hoping it settles.

Moving to a new host: prepare the new instance's networking, IPv6, mDNS and persistent storage first, but do not start it on the same identity while the old one is still up. Stop the old instance, then restore the full backup, keeping the bridge config and the network identity stable. Only once that is confirmed working do you close the rollback window on the old instance.

Lost storage: if you hold a verified full backup, restore it on the same Stable version. If all you have is a config backup, accept that you are recommissioning, and clear the old relationships on each controller before you pair again. Only when there is no usable backup at all do you move to a disaster reset — and treat rebuilding the controllers, Matter Hub and the automations as a project of its own, not an afternoon task.

What you are seeing, what to look at, and the fix that does not make it worse

flowchart TD
  A["A bridge or a controller
is not behaving"] --> B["Commissioning itself fails,
or the bridge is never found"]
  A --> C["It commissioned fine before,
and now shows No Response"]
  A --> D["The bridge itself shows Failed"]
  C --> E{"Is it one controller,
or every controller?"}
  E --> F["Just one: look at that
controller and its hub first"]
  E --> G["All of them: repair the shared
network, then Force Sync or
restart that one bridge"]

On this version, the very last row above has one extra wrinkle worth its own diagram: Factory Reset only actually runs against a bridge that is already Running. If you call it against a bridge that is Stopped or Failed, that bridge may simply be started — with no reset having run at all. Cross-check the fabric and commissioning status after the action either way, because a bridge that just started can look superficially like one that was reset.

stateDiagram-v2
  direction LR
  state "Stopped" as Stopped
  state "Failed" as Failed
  state "Running" as Running
  state "Reset actually runs" as Done
  Stopped --> Running: reset call just starts it
  Failed --> Running: reset call just starts it
  Running --> Done: reset runs for real

The questions that come back around

Where to go from here