A Zigbee2MQTT update lands, and an hour later a router has gone quiet, a cover command throws an error, or a converter that worked yesterday doesn’t. The reasonable instinct is to downgrade Zigbee2MQTT to the previous version that behaved. The official docs only describe moving forward, so the path back has to be pieced together.
This is for Practitioners running Zigbee2MQTT on Docker, as the Home Assistant add-on, or on bare metal, who want to roll back without re-pairing everything. Zigbee2MQTT keeps all of its state in a folder on your own machine, so a rollback never involves a cloud account. It does involve being careful about which files you restore.
This is research synthesis. No downgrade was performed on this site’s hardware, and nothing here claims to have run 2.14.2. The sources are the official Docker, Linux, configuration-update and add-on pages, Home Assistant Community threads and GitHub issues, as of October 2026. Where a step is our own reasoning rather than something a source states, it says so.
The short answer
Rolling back is possible, but Zigbee2MQTT doesn’t document it for any install method. The Docker guide and Linux guide cover forward updates only, and the add-on README is silent.
The safe route is not “install the old version over the new data and hope.” Restore the copy of your data folder taken before the update, then run the older release against it. If you have no such copy, read the migration section first.
What a Zigbee2MQTT install is made of
Four layers get mixed up in rollback threads. This breakdown is our own synthesis from the docs, not an official list.
| Layer | Where it lives | Does a version change touch it? |
|---|---|---|
| Zigbee2MQTT application | Docker image tag, add-on version, or the installed release | Yes, this is the thing you roll back |
| Data folder | configuration.yaml, database.db, coordinator_backup.json, state.json | Can be rewritten by the newer release, including a settings migration |
| Coordinator firmware | Flashed onto the adapter | No, it is flashed separately |
| Home Assistant entities | HA’s entity registry, created via MQTT discovery | Indirectly. A release can change what it publishes via discovery, and HA keeps entities until they are removed |
The coordinator firmware row matters because people expect “downgrade” to undo everything. It doesn’t. If your problem started with an adapter firmware flash, rolling back the application won’t help, and our coordinator firmware update guide covers that layer on its own.
Before you update: the one-minute backup
Back up the whole data folder with Zigbee2MQTT stopped. On Docker that folder is the mounted volume, which the Docker guide maps as ./data:/app/data. Name the copy after the version you are leaving, so you know later what it matches.
# stop Zigbee2MQTT before copying docker compose stop zigbee2mqtt # then name the copy after the version you are on now cp -a ./data ./data-backup-2.14.1
The service name zigbee2mqtt is representative. Use whatever your Compose file calls it. If you have no shell on the host, the frontend has offered a “Download data folder backup” button since 1.26.0, under Settings → Tools on current builds. It gives you the same folder as a zip, which our coordinator backup and restore guide covers in more detail.
Two things that look like backups are not substitutes. The rolling database.db.backup next to the live file (see our database.db recovery article) is a single copy written by whichever release is running, so our reading is that after the update it no longer reflects the old version. The migration’s own configuration.yaml backup, covered below, holds settings only.
Values set through the Home Assistant add-on options or through environment variables are not written to configuration.yaml, and the configuration-update page says they may need manual changes. A data-folder copy doesn’t capture them, so write down your add-on options before you touch anything.
Roll back on Docker
The Docker guide documents three tag styles: latest, latest-dev for the dev branch, and exact version tags, with 2.0.0, 2.0 and 2 given as examples. The documented update procedure is to pull the image and recreate the container, which for Compose means docker compose pull followed by docker compose up -d.
The rollback is that same procedure with a different tag, plus restoring the folder. The order is our synthesis, since the guide never describes it.
- Stop the container.
- Move the current
./dataaside rather than deleting it, so you can inspect it later. - Copy the pre-update backup back to
./data. - Change the image line from
latestto the exact previous version. - Pull and start.
services:
zigbee2mqtt:
# exact tag instead of latest
image: koenkk/zigbee2mqtt:2.14.1
volumes:
- ./data:/app/data
# other keys unchanged
docker compose stop zigbee2mqtt mv ./data ./data-failed-update cp -a ./data-backup-2.14.1 ./data # edit the image tag, then: docker compose pull docker compose up -d
Use the full version rather than a shorter tag. The guide documents 2.0 and 2 as tag styles but doesn’t say whether they follow patch releases, so the full version is the only unambiguous pin. Leave it pinned until a release that fixes your problem exists.
Restoring the old folder also discards anything changed since the update: a device paired or renamed in between won’t be in the restored database.db.
Our view: with more than a handful of mains-powered routers, pin a tag you have actually run rather than floating on latest. With latest, the next pull, yours or an auto-updater’s, decides which release the whole mesh runs. The pin costs one line.
Roll back on the Home Assistant add-on
This is the awkward one. A community thread on downgrading add-ons in general (2021 to 2024) reports that Home Assistant has no native UI option to pick an older add-on version. It describes three routes.
- Restore a backup that contains the older add-on version. Described as the conventional route and the only built-in one. Some users report a partial restore selecting only the Zigbee2MQTT add-on. Others in the same thread say it didn’t work for them.
- Edit the version field inside a partial backup. Proposed, never confirmed. We would not count on it.
- Install the older version as a local add-on from a downloaded ZIP. One poster reported success in April 2022.
All of this is community experience and some of it is years old. Home Assistant’s own backup documentation, as checked for this article, doesn’t describe add-on rollback. Check what your HA version’s backup screen offers before relying on any of it.
Whichever route you take, copy the Zigbee2MQTT data folder separately first. On the add-on it is wherever the data_path option points. Community threads show /share/zigbee2mqtt on some installs, so read your own add-on options rather than assuming a path.
The add-on README separates stable (official releases) from Edge (dev branch). Add-on versions are the Zigbee2MQTT version plus an add-on release number, such as 2.14.1-1. A 2020 thread suggested switching to Edge temporarily since both share a data path, but that predates 2.0 and moves you to dev, not to an older release.
Bare metal: what the docs do not say
The Linux install guide covers installing and updating forward through the update script, with no downgrade or version-pinning instructions. We won’t invent a command for it. The undocumented general shape matches Docker: stop the service, restore the pre-update data folder, and install the target release the way you installed the current one. If your host also had a Node.js bump, our Node.js 20 upgrade guide covers why the runtime can matter separately from the application version.
The configuration-migration caveat
Do not assume an older Zigbee2MQTT release can read a configuration.yaml that a newer release has already migrated. The docs don’t say it can. Restore the data folder copy from before the update instead.
Since v2.0.0, Zigbee2MQTT migrates configuration.yaml automatically. Migrations are keyed to a version setting inside the file, not to the application’s version, and are applied in sequence until the file reaches the current one. Each step first saves a backup named by settings version (the docs’ example is configuration_backup_v1.yaml) and writes a log such as migration-1-to-2.log. The page warns against editing version by hand and never addresses running an older release against a migrated file.
This is not a one-off 1.x to 2.x event. Community threads reference settings versions 4 and 5 under 2.x, so a rollback between two 2.x releases can cross a migration too. Our suggested check: look in the data folder for a configuration_backup_v<N>.yaml or migration-<N>-to-<M>.log dated the day you updated. If one exists, the update rewrote your settings, and that backup is the pre-migration file. If none exists, the settings file was probably left alone, though database.db is a separate question.
Across the major version the advice is firmer. The 2.0 breaking-changes discussion describes forward migration only. On 2.x, roll back within 2.x; going back to 1.x is not something we’d recommend.
Why some readers are rolling back from 2.14.2
Zigbee2MQTT 2.14.2 was released on 1 October 2026, per the GitHub releases page. The truncated release notes we could read list no breaking changes. The two reports below are individual setups: 2.14.2 is a release with some open reports, not a release we’re calling broken.
Issue 33306: a reporter on a ZBT-2 coordinator with 21 Niko mains routers says the routers stopped answering unicasts roughly 33 to 38 hours after start on 2.14.2, twice, and that reverting to 2.14.1-1 restored stability. Recovery needed power-cycling the routers. Opened 2026-10-07, open with no replies when read. One report, one setup.
Issue 33278: setting position on a group of Tuya TS130F covers fails after 2.14.2 with a TypeError, which the reporter traced to converter code reading meta.device, undefined for group commands. Individual devices and group state commands still worked. The issue shows as closed (last activity 2026-10-06) and references a zigbee-herdsman-converters fix PR (#13381). We couldn’t confirm which release carries the fix.
A 2.14.x cover problem that looks like inverted opening and closing is a separate issue and isn’t covered here.
Before rolling back for a bug like the second one, check whether a newer patch already fixes it. The latest-dev tag and the Edge add-on track the dev branch. Dev is not stable, so use it as a test, not a destination.
After the rollback
Entities created by MQTT discovery under the newer version can outlive it in Home Assistant’s registry, so look through your entities for leftovers or changes. Our orphaned-entities guide covers cleaning those up, and our bridge/state article covers the case where everything shows unavailable after the restart.
If the log complains about the database after you restore, the database.db recovery article covers that file, and the coordinator backup guide covers the network-state side, which is a different scope from the application version.
Then subscribe to the GitHub issue for your problem so you hear when a fixed release arrives. That is when you unpin the tag. Next time, copy the data folder before updating, read the release notes, and update on a day you have time to deal with the result.
FAQ
Can you downgrade Zigbee2MQTT to an older version?
Yes in practice, though no official procedure exists. Restore the data folder copy from before the update, then run the older release.
Will downgrading Zigbee2MQTT lose my paired devices?
Not if you restore a pre-update copy of the data folder, since the paired-device state lives there. Anything you paired or renamed after the update won’t be in that copy.
How do I pin a Zigbee2MQTT version in Docker?
Replace latest with an exact version tag in your image line, then pull and recreate the container. The Docker guide documents exact tags such as 2.0.0.
How do I roll back the Zigbee2MQTT add-on in Home Assistant?
There’s no documented UI option. Community reports describe restoring a backup that holds the older version, or installing the older version as a local add-on from a ZIP. Copy the folder your add-on’s data_path points to first, and check your current HA backup screen.
Does downgrading Zigbee2MQTT change my coordinator firmware?
No. The adapter firmware is flashed separately from the application, so rolling back the application leaves it alone.
What we verified, and what stays unknown
Verified from the sources: no official install page documents a downgrade, Docker exact-version tags are documented, and the migration backs up configuration.yaml by settings version and runs in sequence. The four-layer split is our synthesis.
Two things are unknown: whether an older release reads a configuration.yaml a newer one migrated, and whether it can read a database.db a newer one wrote. One anecdotal forum snippet described a restored folder showing zero devices; nothing here is built on it.
So the advice is the same either way: restore the folder from before the update. A controlled downgrade on a spare Docker install would close both gaps; that hasn’t been run here. Everything involved stays local, and the only thing you wait on from anyone else is the upstream fix.