Fix the Home Assistant Z-Wave JS Version Mismatch in Three Steps
This error is a software mismatch, not a failed Z-Wave radio or an erased network. Z-Wave is the local wireless network used by many switches, sensors, and locks. Home Assistant connects to a small server program that sits between Home Assistant and the Z-Wave adapter—the USB stick or network radio that talks to those devices. Home Assistant 2026.7 expects that server to speak API schema 49. An older server can still know every paired device and still be rejected because the two programs no longer speak the same version of the connection language.
- Identify the server Home Assistant is using. Open Settings → Z-Wave → Network information and note the Server URL. If that screen cannot load, use the version in the error and check whether Z-Wave JS appears under Settings → Apps or runs on another computer.
- Update that server in place. Install the latest stable version from its existing update channel. It must be at least Z-Wave JS app 1.4.0, Z-Wave JS UI Docker 11.19.1, or
zwave-js-server3.9.0 for Home Assistant 2026.7. - Restart the updated server, then reconnect Home Assistant. Wait for the server to finish starting. If the integration does not reconnect on its own, reload it once and confirm it still points to the same intended server address.
Do not remove the integration to make the warning disappear. Deleting the integration, excluding devices, or resetting the adapter does not install a newer server. It only adds recovery work to a version problem.
What “Server Version Incompatible” Actually Means
A Home Assistant Z-Wave setup has several layers. The Z-Wave integration creates devices and entities in Home Assistant. A separate Z-Wave JS server bridges that integration to the driver, which controls the adapter and talks to the devices. Home Assistant reaches the server through a local WebSocket address, usually on port 3000.
The version numbers shown in Z-Wave JS UI can therefore look unrelated. Its UI version, driver version, and server version are different pieces. Updating only Home Assistant Core or seeing a recent driver number does not prove the server layer is recent enough.
For the July 2026 release, Home Assistant's official release notes set these minimums:
| Your installation | What to update | Minimum for Home Assistant 2026.7 | Where the update happens |
|---|---|---|---|
| Home Assistant OS with the official Z-Wave JS app | Z-Wave JS app | 1.4.0 | Home Assistant's Apps area |
| Z-Wave JS UI running in Docker | Z-Wave JS UI container image | 11.19.1 | The Docker host, Compose stack, or container manager |
| Manually installed or custom server | zwave-js-server | 3.9.0, schema 49 | The external host's package or service manager |
As of July 24, 2026, newer stable releases are available: Z-Wave JS app 1.5.0, Z-Wave JS UI 11.22.0, and server 3.10.0. Install the latest stable version offered by the update path you already use. The table gives the compatibility floor that clears Home Assistant 2026.7's schema check; it is not a request to install three different programs.
First Find Which Z-Wave Server Home Assistant Uses
Open Settings → Z-Wave → Network information and record the Server version and Server URL. If the network information cannot load while the handshake is failing, use the version in the error message and inspect the app or external host you originally configured. The URL is the best clue:
ws://core-zwave-js:3000points to the official Home Assistant Z-Wave JS app.- An IP address, another hostname, or a separate machine on port 3000 usually points to Z-Wave JS UI or a self-run server.
- If the Z-Wave JS UI dashboard still controls devices while Home Assistant shows the version error, the radio network is alive; Home Assistant is rejecting the older server interface.
Also check Settings → Apps. If the official Z-Wave JS app is installed and your integration is configured to use it, that is the component to update. If your adapter is attached to a Raspberry Pi, NAS, or Docker host somewhere else, update the server there. Do not install a second server just because the first one has no Home Assistant update button.
Path 1: Update the Official Home Assistant Z-Wave JS App
Open Settings → Apps → Z-Wave JS and install the offered stable update. Confirm the displayed app version is at least 1.4.0; Home Assistant's current stable channel may offer a newer version. Once the update finishes, let the app start and wait for its log to show that the driver is ready.
Return to Settings → Z-Wave → Network information. The integration should reconnect by itself. If it remains in retry mode after the app is ready, reload the integration once. Confirm the running server is at least 3.9.0 and still uses the expected URL.
If the managed app page offers no update, check Settings → System → Updates and Settings → System → Repairs. Record the Home Assistant, operating system, and Z-Wave JS app versions before asking for help. Installing Z-Wave JS UI alongside the official app can create two services competing for one adapter. Do not uninstall the official app or choose an option that deletes its data merely to perform an update.
Path 2: Update a Z-Wave JS UI Docker Container
A Docker-based Z-Wave JS UI server is not updated by Home Assistant. Use the same Docker Compose file, stack, Portainer project, or container manager that created it. Update the image to the latest stable Z-Wave JS UI release—at least 11.19.1 for Home Assistant 2026.7—then pull and redeploy the container. Merely downloading a new image or restarting the old container leaves the old software running.
Before redeploying, record the existing settings that make this server yours:
- the persistent store/data volume—the folder that keeps the server's settings—normally mounted at
/usr/src/app/storeinside the container; - the adapter mapping, preferably its stable
/dev/serial/by-id/…path; - the network security keys, serial settings, and region;
- the WebSocket port, hostname, and network address Home Assistant already uses.
Keep the volume. Do not use docker compose down -v, and do not replace the existing store mount with a new empty volume. The -v option removes named volumes and can discard the settings and metadata you are trying to preserve.
Redeploy with the same mappings, wait for Z-Wave JS UI to show the network, and confirm WS Server—the switch that lets Home Assistant connect—remains enabled under its Home Assistant settings. Then let Home Assistant reconnect. If Z-Wave JS UI has your devices but Home Assistant still reports the old server version, Home Assistant may still be pointed at an older container or another host.
Path 3: Update a Self-Run Z-Wave JS Server
If the server was installed with NPM, systemd, a custom container, or another package manager, Home Assistant cannot update it. Update the same installation that supplies zwave-js-server to the latest stable release—at least version 3.9.0 for Home Assistant 2026.7—keep the same adapter path, storage, keys, and service account, then restart that service.
There is no single safe command for every self-managed installation. A global NPM install, a local project, a Snap package, and a service launched from a fixed directory can each update differently. Confirm the package source can provide a compatible release and that the running service uses the package you changed. If the package channel is stuck on an old version, do not repeatedly reinstall over the working data. Plan a documented migration to the official app or Docker. Restore a known-good Home Assistant backup only as a last resort, after checking its date and accepting that later configuration changes may be lost.
The official Home Assistant documentation treats this as an advanced path. If remote radio placement is why you chose it, keep that architecture—but document the host, update method, data path, and owner. Tara's Z-Wave JS versus Z-Wave JS UI guide explains when that separation is worth the extra maintenance.
Why Home Assistant Shows No Update Button
The update control belongs to the system that manages the server. Home Assistant can offer updates for its official app. It cannot reach into a remote Raspberry Pi, NAS, Docker host, NPM installation, or third-party package repository and replace that software.
If Z-Wave JS UI appears as a community app inside Home Assistant, update it from that app's repository page. Its package version may not match the upstream Z-Wave JS UI number shown in the 2026.7 notes, so verify the running server version after the update. The current official Z-Wave documentation says the older Z-Wave JS UI app path is being phased out in favor of the official Z-Wave JS app. Treat migration as a planned backup-and-restore task, not an emergency click while the network is down.
If no compatible update exists for your package source, the safe choices are to remain temporarily on the last Home Assistant version that worked or migrate the server deliberately. Do not solve a missing package by deleting devices or changing Z-Wave security keys.
How to Confirm the Repair Worked
- Open the server's log or dashboard and confirm it finished starting without an adapter-lock or storage error.
- Give the Home Assistant integration a moment to reconnect. Reload it once only if it stays in retry mode after the server is ready.
- Open Settings → Z-Wave → Network information and confirm the running server meets the required version and the URL is the intended host.
- Wait for mains-powered devices to return, then wake one battery device only if its fresh readings are needed immediately.
- Test one light, switch, lock, or sensor before declaring the whole network recovered.
If the message changes from “server version incompatible” to “cannot connect”, the version gate may be fixed but Home Assistant cannot reach the server. Check that the server is running, the WebSocket service is enabled, the saved host and port are correct, and no firewall change blocks the local connection. Tara's guide to devices unavailable after a Home Assistant restart covers that separate connection problem.
If Home Assistant Still Reports the Old Version
- Confirm the running version, not the downloaded version. Docker hosts can keep an old container running after a new image is pulled.
- Compare the server URL. Home Assistant may still point to an old IP address, old hostname, or second server on port 3000.
- Look for duplicate services. The official app, a community app, and a remote container should not compete for the same adapter.
- Check the app or service log. An adapter permission, USB mapping, or data-volume error can prevent the new server from starting even though the update installed.
- Reload once after the server is ready. Repeated Home Assistant restarts do not upgrade an external server.
Only if the saved Server URL is genuinely wrong, use the Z-Wave integration's Reconfigure flow. For an external server, clear the checkbox labeled Use the Z-Wave Supervisor app, then enter the existing external WebSocket address. Do not blindly change a working address during a version error.
Before a wider recovery, create a current Home Assistant backup and download a Z-Wave network backup from the Z-Wave panel when available. Keep the security keys with the system record. Those precautions protect a future adapter migration; they are not a reason to reset a healthy adapter now.
What Not to Reset or Re-Pair
Do not use exclusion, inclusion, factory reset, integration deletion, route rebuilding, or security-key replacement as a response to this message. None of those actions installs the newer server API. Paired device information remains on the Z-Wave adapter, while server settings and device metadata live in the app or server data store.
Resetting the adapter can erase the network. Changing keys can stop secure devices from working. Deleting the integration can remove Home Assistant's device and entity records. A clean in-place server update avoids all three risks.
Does the Fix Make Z-Wave Cloud-Dependent?
No. Home Assistant classifies the Z-Wave integration as Local Push, and the integration talks to the Z-Wave JS server over your local network. You may need internet access to download the app, package, or container image, but everyday Z-Wave control does not require a Z-Wave vendor cloud.
Z-Wave JS UI also offers MQTT features, but Home Assistant's Z-Wave integration does not need MQTT for this connection. Its normal path is the local WebSocket server. If the internet goes down after the update is installed, local automations and controls should continue as long as Home Assistant, the server, the adapter, and your home network remain powered.
Tara's Practical Recommendation
For a new Home Assistant OS installation, use the official Z-Wave JS app unless remote adapter placement or reboot isolation creates a real reason to separate it. For an existing remote Z-Wave JS UI setup, update it in place and document the server host, container or package source, persistent data path, adapter mapping, security-key location, and WebSocket URL.
If you want that ownership and recovery path designed into a supported system, Tara's configured Home Assistant setup keeps the local server, radios, update responsibilities, and household handoff in one plan.
FAQ
Which Z-Wave JS version does Home Assistant 2026.7 require?
Use the official Z-Wave JS app 1.4.0 or newer, Z-Wave JS UI Docker 11.19.1 or newer, or a self-run zwave-js-server 3.9.0 or newer using schema 49. Install the latest stable version offered by the existing setup; later Home Assistant releases may raise these minimums.
Why is there no Z-Wave JS update button in Home Assistant?
The server is probably external. Home Assistant can update its managed app, but a Docker container, remote Raspberry Pi, NAS service, or self-run package must be updated where it was installed.
Did the incompatible-server error erase my Z-Wave network?
No. It describes a software protocol mismatch. Do not exclude devices, reset the adapter, delete the integration, change keys, or re-pair the mesh. Update the server first.
Why did restarting Z-Wave JS not fix the error?
A restart launches the same installed version. Docker users need to pull and redeploy a compatible image. Self-run users need to update the package or service that is actually running, then restart it.
How do I know which Z-Wave server Home Assistant is using?
Open Settings → Z-Wave → Network information and record the Server URL and Server version. A remote IP address or hostname usually identifies an external server. Confirm that address matches the host you updated.
Does Z-Wave JS UI need MQTT for Home Assistant?
No. Home Assistant connects to the Z-Wave JS server over a local WebSocket. MQTT is an optional Z-Wave JS UI feature and is separate from the integration connection.