Home Assistant DNS Failure: Zigbee2MQTT Fixes

Direct answer: When Zigbee2MQTT and several Home Assistant add-ons go offline together, first determine whether the failure is DNS, MQTT, or the Zigbee adapter—do not reset the coordinator or re-pair devices. A message such as getaddrinfo ENOTFOUND, EAI_AGAIN, Name does not resolve, or Temporary failure in name resolution points toward DNS. ECONNREFUSED, an authentication failure, or a TLS error means the hostname resolved but the broker connection failed. Serial-port and adapter initialization errors belong to a different branch.

Symptoms this guide covers

This workflow is for Home Assistant installations where Zigbee2MQTT, Mosquitto, or another app stopped communicating after an update, restart, network change, or host-name change. Typical symptoms include all Zigbee entities becoming unavailable at once, Zigbee2MQTT restarting repeatedly, the Zigbee2MQTT frontend loading while MQTT never connects, several apps failing to resolve internal names, or logs naming a broker host that cannot be found.

It does not assume that Home Assistant 2026.9 has one universal DNS defect. The 2026.9 release is useful version context because settings and connectivity surfaces changed, but a temporal association is not proof of a Core regression. Match the exact log layer before changing anything. The same diagnostic order also applies to later releases unless their release notes identify a more specific breaking change.

Preserve evidence before restarting anything

Download or confirm a recent Home Assistant backup before changing app configuration.
Copy the first meaningful Zigbee2MQTT error after startup, not hundreds of repeated reconnect lines.
Record the configured MQTT server value without copying its password.
Note whether Mosquitto, Zigbee2MQTT, and other affected apps are running, stopped, or restarting.
Record whether the failure began after a Core, Operating System, Supervisor, app, router, VLAN, or DNS change.

Remove usernames, passwords, access tokens, public IP addresses, device identifiers, Wi-Fi names, and coordinates before sharing logs. A broker URL may embed credentials, so redact it carefully.

Read the error by diagnostic layer

Log pattern	Likely layer	Least-destructive next check
`ENOTFOUND`, `EAI_AGAIN`, “name does not resolve”	DNS/name resolution	Verify the configured hostname and whether other apps can resolve internal names.
`ECONNREFUSED` or connection refused	Broker service/port	Confirm Mosquitto is running and listening at the configured port.
Not authorized, bad username/password	MQTT authentication	Confirm the dedicated broker account and secret reference without exposing credentials.
Certificate, TLS, or hostname mismatch	MQTT transport security	Check scheme, certificate name, time, and CA configuration.
Adapter not found, cannot open port, failed to connect to adapter	Zigbee coordinator	Check the stable device path, exclusivity, power, and adapter type.
Only one or a few devices unavailable	Zigbee mesh/device	Inspect routers, battery, signal, and the individual device before touching MQTT.

Step 1: decide whether the outage is broad or isolated

A broad simultaneous outage is the strongest clue. If every Zigbee entity becomes unavailable while Zigbee2MQTT reports an MQTT connection problem, the coordinator may still be operating normally. Zigbee2MQTT translates Zigbee events into MQTT messages; when the broker path breaks, Home Assistant stops receiving those messages and can make a healthy mesh look dead.

If only one device fails while Zigbee2MQTT remains connected to MQTT and other devices update normally, DNS is unlikely. Start with the individual device, its battery, nearby routers, interference, or last-seen history. If Zigbee2MQTT cannot initialize its adapter before it attempts MQTT, use the serial-port and coordinator diagnostic guide as the closer route.

Step 2: verify the MQTT server value

Zigbee2MQTT requires an MQTT server connection. Its official configuration documentation shows server values such as mqtt://localhost:1883 and notes that the Home Assistant Mosquitto app commonly uses the internal host core-mosquitto. The correct value depends on how Zigbee2MQTT is installed. A Home Assistant app, a separate Docker container, and a remote host do not share the same meaning of localhost.

For the Home Assistant app arrangement, compare the value with the current app documentation and your broker configuration.
For separate Docker containers, confirm both containers share the intended network and that the broker service name still exists.
For a remote broker, confirm the hostname or fixed address still identifies the same machine.
Check for spelling mistakes, an obsolete domain suffix, an accidental space, the wrong URI scheme, or an incorrect port.

Do not publish the complete configuration when asking for help. Zigbee2MQTT supports placing the server, username, password, and network key in a separate secrets file; preserve those boundaries.

Step 3: separate DNS from reachability

DNS answers the question “what address belongs to this name?” Reachability answers “can the client connect to that address and port?” These are different failures. A resolution error occurs before authentication. A connection-refused error normally means resolution succeeded and a host actively rejected the requested port. A timeout can indicate routing, firewall, a stopped service, or a host that never replied.

When an authorized diagnostic environment shows that the broker is reachable by numeric address but not by its configured name, that is useful evidence for DNS. Use the comparison only as a temporary test. Permanently hard-coding an internal app address may create a fragile setup because managed addresses can change. Restore the documented hostname-based configuration after correcting name resolution.

If multiple unrelated apps fail to resolve internal or external names at the same time, widen the investigation to the Home Assistant host, Supervisor/app network, upstream DNS server, router, VLAN rules, and recent network changes. If only Zigbee2MQTT fails and every other app resolves names normally, first scrutinize its exact server value and execution environment.

Step 4: verify Mosquitto without changing Zigbee

Confirm that the broker is installed, started, and not trapped in its own restart loop. Read its log at the same timestamp as the Zigbee2MQTT attempt. If Mosquitto records no incoming attempt while Zigbee2MQTT reports a DNS error, the connection likely never reached the broker. If Mosquitto records the attempt and rejects it, focus on credentials, permissions, client identity, or TLS instead of DNS.

Use a dedicated non-administrator MQTT account with only the access required by the deployment. Do not disable authentication as a diagnostic shortcut on a network you do not fully trust. If credentials recently changed, update the secret in one controlled step, restart only the affected client, and inspect the first new log sequence.

Step 5: interpret authentication and TLS errors correctly

An authentication error proves more than it appears to: the client reached something capable of speaking MQTT. Rechecking DNS repeatedly will not repair a rejected username or password. Verify the account, password source, ACL, and whether the broker expects anonymous or authenticated connections.

TLS errors also need their own branch. Confirm whether the configured URL begins with mqtt:// or mqtts://, whether the port matches that choice, whether Home Assistant’s clock is correct, whether the certificate covers the broker hostname, and whether the issuing CA is trusted. Do not bypass certificate verification permanently simply to silence an error; that can hide interception or a wrong destination.

Step 6: check the coordinator only after MQTT is healthy

Once Zigbee2MQTT reaches and authenticates to MQTT, any remaining startup error can be evaluated separately. Official Zigbee2MQTT troubleshooting notes that many startup crashes come from inability to communicate with the adapter. Look for USB discovery failures, an incorrect adapter type, a changed device path, another process holding the port, insufficient power, or a remote adapter that changed address.

Prefer stable device identifiers over transient names such as /dev/ttyUSB0 when the platform exposes them. For network coordinators, use a reserved address when the vendor recommends one and validate the correct TCP mode. Never flash firmware, erase coordinator storage, or create a new Zigbee network merely because the MQTT broker was unavailable.

Safe repair paths and what each result means

The hostname is wrong or obsolete

Correct only the MQTT server value, save, and restart Zigbee2MQTT once. A successful broker connection without adapter errors confirms the name was the blocking layer. If the new hostname resolves but authentication fails, the DNS problem is fixed and the next layer now needs attention.

The broker is stopped

Start or repair Mosquitto, then observe its log before restarting other services. If it stops again, investigate that failure rather than creating a restart loop. Storage exhaustion, invalid configuration, port conflicts, and permission problems require different repairs.

Only internal names fail

Review recent router, DNS, VLAN, Supervisor, and host changes. Restore the documented resolver path rather than scattering numeric addresses across configurations. After the correction, verify at least two affected names and then restart only the clients that did not reconnect automatically.

The broker rejects credentials

Update the dedicated client’s secret or broker account as appropriate. Do not paste passwords directly into logs or support posts. A clean successful CONNACK or a normal Zigbee2MQTT “connected to MQTT server” message is the expected validation result.

MQTT works but the adapter fails

Preserve the Zigbee network data, then check the configured adapter path and type, USB extension and power, device exclusivity, and firmware compatibility. This branch is independent of DNS; changing resolver settings further is unlikely to help.

Verification checklist

Mosquitto remains running and its log shows the expected client connection.
Zigbee2MQTT completes startup without DNS, authentication, TLS, or adapter errors.
The Zigbee2MQTT frontend shows the existing network rather than an empty newly formed network.
Home Assistant receives fresh state updates from multiple mains-powered and battery devices.
A controlled command reaches one non-safety-critical test device and its resulting state returns.
No unrelated app continues reporting the same resolution failure.

Do not validate using door locks, alarms, garage doors, heaters, medical equipment, or other safety-critical devices first. Choose a lamp or sensor where a delayed or duplicated command cannot create harm.

Rollback and recovery

If a single configuration change makes the condition worse, restore the previous value from your notes and restart only the affected service. If several settings were changed together, stop and restore the known-good app configuration or backup rather than guessing. A Home Assistant backup can restore configuration, but confirm its date and encryption key availability before depending on it.

If Zigbee2MQTT unexpectedly presents onboarding or no longer recognizes the network, stop before creating a new network. Verify that the correct data directory, configuration file, coordinator, and network key are mounted. Preserve the current directory before any reinstall. Re-pairing should be a last resort after confirming that the coordinator backup and network data cannot be recovered.

When to escalate

Escalate to the relevant project only after isolating the layer. For a Home Assistant host or Supervisor DNS failure affecting several apps, include installation type, Core/Operating System/Supervisor versions, sanitized resolver symptoms, the time the issue began, and whether a rollback changes it. For Zigbee2MQTT, include its version, installation method, sanitized first error, broker type, and coordinator model. For Mosquitto, include the broker-side rejection or startup error without credentials.

Open upstream issues are reports, not proof that every similar installation has the same defect. Search for your exact error and version, read maintainer responses, and avoid claiming a universal regression until it is confirmed or documented in release notes.

Prevention

Keep a current encrypted backup and separately store the recovery key.
Record the broker hostname, port, TLS mode, and installation topology without recording its password.
Use stable hostnames and reserved addresses where the relevant documentation recommends them.
Read breaking-change notes before major Home Assistant, Zigbee2MQTT, broker, or operating-system updates.
Update one layer at a time when practical and verify MQTT plus several devices afterward.
Retain a short sanitized baseline log showing a normal startup sequence.

Evidence and testing disclosure

Applies to: Home Assistant 2026.9-era installations using Zigbee2MQTT with Mosquitto or another MQTT broker; the layered method also applies to later versions. Expected result: the configured broker name resolves, Zigbee2MQTT authenticates, the adapter initializes, and existing devices resume state updates without rebuilding the network. Verification method: compare the first startup error with broker logs and validate one layer at a time. Testing status: this guide synthesizes documented behavior and diagnostic logic; Troubliq did not reproduce every installation topology or claim a universal 2026.9 regression. Last reviewed September 29, 2026.

Related Troubliq diagnostics

Use the Home Assistant Error Decoder to classify a sanitized log message. If the broker connects but the coordinator does not, follow the serial-port and radio checklist. For current version-specific reports, check Home Assistant Problems Right Now. Remove all private data before sharing logs in the Troubliq community.

Home Assistant DNS Failure: Zigbee2MQTT and Add-ons Offline