When Your Smart Home Hub Dies: The Local-First Disaster Recovery Playbook

Your hub fails on a Tuesday. The SD card corrupts, or the mini PC won’t boot, or the Zigbee stick stops responding after a power glitch. You open your backup and discover it is encrypted, and the key was stored on the machine that just died.

That is the reason for this guide. A Home Assistant backup is one artifact in a seven-layer recovery stack. The Zigbee network, the Z-Wave adapter’s memory, Matter fabrics and setup codes, Thread credentials, and ESPHome YAML and secrets each have their own export path, their own failure mode, and their own answer to “what breaks if lost?” The layer people forget is the one artifact that cannot live inside the backup: the backup encryption key.

The Recovery-Artifact Map

Layer	Recovery artifact	Where it lives	How it is exported	What breaks if lost
1. Home Assistant config and apps	Full backup file (SecureTar, encrypted by default) plus the encryption key	Local backup location, optional Home Assistant Cloud slot, your off-device copies	Settings > System > Backups, then download	Automations, dashboards, integrations and device configuration; encrypted backups cannot be opened without the key
2. ZHA Zigbee network	Zigbee network backup	Inside ZHA’s automatic backups and the coordinator’s memory	Automatic backups; manual backup from the configuration page under Network Settings	Zigbee pairing data; many devices must rejoin, or migration may be impossible
3. Zigbee2MQTT data	coordinator_backup.json (zStack or EmberZNet adapters only)	Zigbee2MQTT data directory	Coordinator backup from Zigbee2MQTT	Coordinator identity on supported adapters; on other adapters there is no documented coordinator backup
4. Z-Wave NVM	NVM binary file from the adapter	Adapter non-volatile memory, downloaded as a binary file	Settings > Connectivity > Z-Wave > Download backup > Download	Network information and paired devices stored on the stick
5. Matter fabric and setup codes	Fabric membership and the device’s QR or numeric setup code	Controller fabric in Home Assistant; the code in your records	Device page > Share device > three dots > Manage fabrics	Fabric membership on the controller; after a factory reset, commissioning is impossible without the code
6. Thread credentials	Thread network credentials (similar to a Wi-Fi password)	The Thread integration and the Companion app	Companion app > Settings > Companion app > Troubleshooting > Sync Thread credentials	Ability to join devices to the Thread network
7. ESPHome YAML and secrets	Device YAML files and secrets.yaml, including per-device API keys	Your config directory or version control	Copy the files out of Home Assistant	Ability to rebuild and OTA-update firmware

Layer 1: Home Assistant Itself

The default automatic backup covers “everything daily, except media, the share folder, and the local apps folder, and keeps the last 3 backups,” storing on the system and on Home Assistant Cloud if you are logged in (Home Assistant — Backups). Pick a time when all locations are available, because otherwise “the backup fails for the locations that aren’t available.”

Retention removes older automatic backups: with daily backups and “keep 7”, anything older than 7 days goes. “These retention settings do not delete manual backups.” The exception is Home Assistant Cloud, which “replaces its previous backup whenever a new backup is uploaded, even if the previous backup was created manually” (Backups).

If backups live only on the device, you “won’t be able to access them easily” — keep a copy on another system outside Home Assistant, and ideally one off-site. The Cloud slot accepts “a backup of maximum 5 GB,” stores “one backup file,” and “always keeps only one backup.”

If you need a schedule the built-in options cannot give you, the backup.create_automatic action builds your own automation, and failure alerts come from “the event entity and sensors of the Backup integration” (Backups). When a backup fails, search for these documented strings: [Errno 5] I/O error, [Errno 30] Read-only file system, Could not lock database within 30 seconds, backup location unavailable, upload to configured locations failed, “Not all apps could be included”, “Automatic backup was created with errors”, restore blocked, restore stuck or “Not found”, and “The provided encryption key was incorrect.” The I/O and read-only errors usually point at the storage itself — treat them as a signal to export your other layers now.

The Key That Cannot Live in the Backup

“Home Assistant encrypts your backups by default.” Cloud backups are always encrypted; other locations are your choice (Backup emergency kit).

The emergency kit is a text file containing the key, plus “the name and address of your Home Assistant, and the date when you downloaded the kit.” Store it “outside Home Assistant.” The documentation is blunt: “Without the encryption key, there is no way to restore an encrypted backup” (Backup emergency kit).

If you change the key, keep the old kit “to restore the backups that you made before the change.” If the key goes missing, Home Assistant “doesn’t have the key of older backups anymore,” there is “no way to restore the backup,” and Nabu Casa “does not store your encryption key and cannot provide support in decrypting backups if the key goes missing” (Backup emergency kit).

Current backups use version 3 of SecureTar, which “encrypts the contents of the backup with XChaCha20-Poly1305 and derives the key from your encryption key with Argon2id,” and “also detects whether a backup file was changed or is incomplete.” Older backups use AES-128 and can still be restored. Metadata is not protected: the backup’s name, date, and Home Assistant version are readable without the key (Backup emergency kit).

Downloading from the backups page decrypts on the fly, and an older backup prompts for its key. You can also download it still encrypted, which is the safer choice when you move files to storage you do not fully control (Backups).

Restore Day

Restoring during onboarding on a new device requires an internet connection, “at least 2 GB of free storage after you upload the backup,” a healthy system (the Observer at http://homeassistant.local:4357 should show Healthy), and storage larger than the old installation’s used space plus at least 2 GB. On a Home Assistant Yellow the eMMC is what matters: “The restore process mainly uses the eMMC, not the NVMe.” And “the size of the backup file is no indication of the size of your installation” — do not size a replacement disk from the backup file (Backups).

“For a larger installation, a restore can take about 45 minutes,” and you must not turn the system off or unplug it during the restore. Migration across hardware works: “you can migrate from a Raspberry Pi to another device.” Plug previously connected controllers and radios — a Z-Wave stick, for example — into the new device first.

After the restore, log in with “the credentials of the system from which you took the backup”; the username and password “must match the ones you used at the time the backup was taken.” If you changed the password after the backup, the old one is the one that works (Backups).

Four things surprise people afterwards: certificates on the http integration mean the restored system stops answering http:// and needs https://; battery devices may need waking; a new host with its own built-in Zigbee radio means “because this is now a different Zigbee radio, you need to migrate Zigbee”; and the recorder database keeps 10 days of history by default, adjustable with purge_keep_days, so expect a history gap (Backups).

Zigbee: ZHA and Zigbee2MQTT

ZHA “performs automatic backups of your Zigbee network,” with manual backups from the configuration page under Network Settings. It supports migration “between different Zigbee adapters based on chips from Silicon Labs, Texas Instruments, or ConBee/RaspBee if the backup was made from inside ZHA.” The old adapter must have been used “in ZHA … and not in deCONZ or Zigbee2MQTT”; radio types are ezsp (Silicon Labs EmberZNet), znp (Texas Instruments Z-Stack ZNP) and deCONZ (ConBee/RaspBee); and the documentation requires firmware 0x26700700 (from 2021-08-18) or later (ZHA integration).

Start at Settings > Connectivity > Zigbee > Migrate. Use a USB extension cable, a USB 2.0 port or powered USB 2.0 hub, and keep the adapter away from USB 3.0 devices. An automatic backup is taken first; choose “Migrate automatically (recommended)” or “Advanced migration” with an older backup.

You may see an “Overwrite Radio IEEE Address” prompt; checking “Permanently replace the radio IEEE address” keeps your devices in the network. Afterwards “both the old and new Zigbee adapters now have the same Zigbee IEEE address,” so do not run the old adapter in the same area unless you change its address. Skip the IEEE migration and “you will have to reconnect many of your devices.” Devices normally “rejoin within one hour,” power-cycling speeds that up, and the old adapter is reset during the process (ZHA integration).

Zigbee2MQTT has its own rules: “Only adapters based on zStack or EmberZNet currently support backing up the coordinator (coordinator_backup.json)” (Zigbee2MQTT — Supported adapters). Its FAQ adds that migration “requires backup and restore support which is so far only implemented for the zstack (Texas Instrument) and ember adapters. Backup and restore is not supported for any other adapters (conbee, ezsp, zboss and zigate)” (Zigbee2MQTT — FAQ).

Here is the trap. ConBee appears in ZHA’s migration matrix and is unsupported for Zigbee2MQTT backup and restore. These are stack-specific rules: a ConBee stick that works with ZHA migration does not thereby become migratable under Zigbee2MQTT. Switching between zStack and ember “might not” require re-pairing, but “results might vary as this is not officially supported” — check every device and re-pair the failures (Zigbee2MQTT — FAQ).

Z-Wave: NVM Is the Network

The documentation recommends a backup “before making any major changes to your Z-Wave network.” It stores “your Z-Wave adapter’s non-volatile memory (NVM), which contains your network information including paired devices. It is stored in a binary file that you can download” (Z-Wave JS).

Go to Settings > Connectivity > Z-Wave > Download backup > Download. “Restore from backup” and “Migrate adapter” live in the same panel. Zooz calls NVM backup “a critical step” for its 700- and 800-series sticks (ZST10 700 and ZST39 800) when migrating or working on firmware (Zooz knowledge base).

Matter and Thread

Home Assistant runs its own Matter controller as an app; the network a controller manages is called a “Fabric,” and the integration talks to the Matter Server over a WebSocket. Bluetooth is used “to pair a device after unboxing or after factory resetting,” not to control it (Matter).

Multi-fabric support is your redundancy lever: “the standard describes that each device should be able to at least support 5 different fabrics simultaneously.” Review membership on the device page under Share device > three dots > Manage fabrics.

The setup code is the most common Matter loss: “If you reset your device you’ll need the QR code or numeric setup code to commission that device again! Without this information, commissioning won’t be possible” (Matter). Your hub backup does not contain the device’s setup code, so record each QR or numeric code outside Home Assistant before you need it.

Thread credentials are “similar to a Wi-Fi password,” and the integration “is currently still a work in progress” (Thread). A border router “connects a Thread mesh network … to other IP networks” and “does not look at the content of these packets, it just forwards them.” Thread “can use multiple border routers in a single network. This increases wireless coverage and reduces the risk of a single point of failure.” Home Assistant “can configure and control only OpenThread border routers built with the REST API,” and networks it creates are named ha-thread-xxxx, where “the last four digits are a network-specific identifier (PAN ID).” Sync credentials to your phone via Companion app > Settings > Companion app > Troubleshooting > Sync Thread credentials.

Thread recovery is not a documented runbook in the sources this guide uses. Export the credentials, record the network identity, and do not assume a restore path exists beyond those pages.

ESPHome: The YAML Is the Backup

ESPHome devices do not live in a restored database; their recovery artifact is the configuration you wrote. Keep the device YAML and secrets.yaml outside the Home Assistant host, in version control or a location you control.

configuration.yaml “is a plain-text file, thus it is readable by anyone who has access to the file,” and !secret only moves literals into secrets.yaml — the nearest file wins, then parent folders up to the main configuration.yaml (secrets.yaml). Centralizing secrets does not encrypt them: “storing secrets in secrets.yaml does not encrypt them,” and the checklist says to back them up (Securing your installation).

The ESPHome API uses port 6053 by default, with encryption set via api: encryption: key: where the key is “a 32-byte base64-encoded string.” When present, “encryption will be enabled for the API”; without a key, “encryption will not be used until it is set.” Configuring the key on the fly “will be implemented in a future release of Home Assistant,” so do not plan around it today (ESPHome — API).

Without API encryption, “anyone on your local network can” control or monitor the device. Generate “a unique encryption key for each device,” “never reuse encryption keys across devices,” keep keys in secrets.yaml, and “never commit this file to version control” (ESPHome — Security best practices).

ESPHome “is designed for deployment on trusted networks,” assumes “network perimeter security (firewalls, network segmentation, VLANs),” and states that “ESPHome devices should not be considered hardened for hostile network environments.” Always set auth: on the web server, which “has no cross-site (CSRF) protection by design.” OTA encryption “reuses the API key,” and the firmware image “contains your Wi-Fi credentials and your API encryption key” — a password “only authenticates the uploader, it does not keep the image confidential” (ESPHome — Security best practices).

Two rebuild traps: with <<: !include the merge is shallow and key-wise, so “the first definition wins” and a later duplicate top-level key is “dropped entirely,” while packages: performs “a recursive deep merge.” Devices using dashboard_import still need “an individual YAML config file” for future OTA updates (ESPHome — esphome component).

This Weekend: A Consolidation Checklist

• Export the Home Assistant backup, including the encrypted file, and confirm a copy exists outside the host.
• Save the emergency kit outside Home Assistant — and every old kit if you have rotated the key.
• Export the Zigbee network from the place your stack supports: ZHA’s manual backup, or the coordinator backup on a supported Zigbee2MQTT adapter.
• Download the Z-Wave NVM file and store it off the stick.
• Record Matter setup codes for every device and note which fabrics it uses.
• Export Thread credentials and record your network identity, including any ha-thread-xxxx name.
• Copy ESPHome YAML and secrets.yaml somewhere you control, with each device’s API key in your secret store.
• Re-check restore prerequisites: free storage, the 2 GB margin, and the radios you will plug in first.

FAQ

Can I restore an encrypted backup without the encryption key?

No. “Without the encryption key, there is no way to restore an encrypted backup.” Home Assistant does not hold older keys after rotation, and Nabu Casa “cannot provide support in decrypting backups if the key goes missing” (Backup emergency kit).

Does the Cloud backup count as off-site?

It is a copy outside your house, but it is one slot: max 5 GB, always encrypted, replaced on every upload (Backups). Keep at least one more copy you control.

Do I have to re-pair every Zigbee device?

Not if you migrate with the IEEE address handled. Without it, “you will have to reconnect many of your devices”; with it, devices normally “rejoin within one hour” (ZHA integration).

What happens to Matter devices after a hub rebuild?

The restored backup brings back the controller and its fabric state. If you factory reset a device, you need its QR or numeric setup code to commission it again (Matter).

Is my Zigbee2MQTT ConBee backup migratable?

No. Backup and restore “is not supported for any other adapters (conbee, ezsp, zboss and zigate)”; only zStack and EmberZNet support coordinator backup (Zigbee2MQTT — FAQ).

How This Guide Was Built

This guide is documentation- and source-based. It draws only on the vendor and project pages cited inline, fetched on 2026-11-04: the Home Assistant backup, emergency kit, securing, secrets, ZHA, Z-Wave JS, Matter, and Thread pages; the ESPHome API, security best practices, and esphome component pages; the Zigbee2MQTT adapters and FAQ pages; and the Zooz NVM backup knowledge base article.

No devices were tested hands-on. Procedures are described as the documentation states them, and date-sensitive items — Thread’s work-in-progress status, ESPHome’s future-release note, ZHA’s firmware threshold — are attributed and should be re-checked.

The Bottom Line

A Home Assistant backup is one artifact in a seven-layer recovery stack: necessary, and insufficient on its own. The artifact that cannot live inside the backup is the encryption key — without it an encrypted backup cannot be restored and Nabu Casa cannot help. Keep the current kit outside Home Assistant, and keep every old kit if you rotate the key.

Around that key, export each remaining layer on its own terms: Zigbee network data in the matrix your application actually supports, the Z-Wave NVM file, Matter setup codes recorded before you need them, Thread credentials and network identity, and the ESPHome YAML and plaintext secrets in a place you control. Recovery is a set of exports, not a single file.

📖 Related Reads

• ToolBrain — tool reviews, LLM comparisons, and AI workflow guides

Cross-links automatically generated from SmartHome Field Guide.

← Back to guides