An MQTT entity that changes from available to unavailable every few minutes may still publish sensor values correctly. The useful clue is the availability topic: Home Assistant is reporting what it receives, not guessing whether the physical device is healthy.
What this failure pattern tells you
This guide uses a narrow diagnostic sequence: confirm the pattern, protect the current configuration, test the smallest likely cause, and verify the result before moving deeper. That approach avoids turning one failed device or automation into a site-wide recovery job.
- State values update, but the device badge repeatedly becomes unavailable.
- The problem begins after broker, router, or Home Assistant restarts.
- Several devices fail together, or only one firmware family is affected.
- The log shows reconnects, socket errors, or duplicate client identifiers.
Most likely causes
- A retained offline payload remains on the availability topic.
- The device uses a short keepalive and unstable Wi-Fi.
- Two clients share the same MQTT client ID and disconnect each other.
- Birth and Last Will payloads do not match Home Assistant’s expected values.
- The broker, add-on, or device clock restarts on a repeating schedule.
Before changing anything
Make a current Home Assistant backup and download it somewhere outside the system. Take screenshots of the affected integration, device, entity IDs, and any relevant automation. Record the exact time of the next failure so the log window stays small. If the issue involves radio hardware, do not unplug it while Home Assistant is writing data.
Step-by-step diagnosis and repair
- Open the MQTT integration and listen to the exact availability topic; record payloads and timestamps without publishing anything.
- Compare the entity’s configured payload_available and payload_not_available values, including capitalization and whitespace.
- Check whether the offline message is retained. A stale retained Last Will can survive restarts.
- Inspect the broker log for repeated connections using the same client ID.
- Give every physical device a unique client ID, then restart only the affected client.
- Check Wi-Fi signal, DHCP stability, power supply, and keepalive settings on the device.
- If multiple devices fail simultaneously, investigate broker or network infrastructure before editing every device.
- After correcting the publisher, clear or replace only the known stale retained availability message using the device’s documented procedure.
How to verify the repair
Do not declare success immediately after a reload. Repeat the original action several times, then observe the system through at least one normal restart or reconnect cycle. Review the log at the exact test time and confirm that the affected entities update normally. If the problem was intermittent, keep a short note of the previous failure interval and monitor beyond it.
Common mistakes to avoid
- Do not publish a blank retained payload to broad wildcard topics.
- Do not disable availability reporting just to hide a real disconnect.
- Do not expose the broker to the public internet while troubleshooting.
A practical decision rule
If several unrelated devices fail at the same moment, investigate shared infrastructure: power, network, broker, radio, host load, or a recent update. If only one model or entity fails while everything around it remains stable, focus on that device’s identity, firmware, configuration, and signal path. Rebuilding a healthy shared integration should be the final option, not the first.
When to restore a backup
Restore only when you can identify a known-good backup from before a harmful configuration change and you understand what newer changes will be lost. A backup is not a substitute for diagnosing failing hardware, interference, duplicate identifiers, or unstable power; those problems will return after restoration.
Frequently asked questions
Can sensor values update while availability is wrong?
Yes. State and availability often use different topics and retained-message behavior.
What does a duplicate client ID do?
Most brokers disconnect the older session when another client connects with the same identifier, creating a repeating online/offline cycle.
Should I delete the MQTT integration?
Usually not. First isolate the exact topic, payload, client ID, and timestamp pattern.
Bottom line
Start with evidence from the affected device, integration, trace, or topic. Protect the working system, change one variable, and verify through the original failure condition. That is slower than random resets for five minutes and much faster than rebuilding an entire smart home unnecessarily.
Deep diagnostic worksheet
Use this worksheet when the quick repair does not hold. The objective is to build a timestamped explanation of the MQTT availability problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.
- Capture the exact availability topic and every payload over a complete online-offline cycle. Include timestamps, retain flags when available, and client connection events from the broker log.
- Compare the observed strings byte-for-byte with payload_available and payload_not_available. Capitalization, whitespace, encoding, and JSON structure matter; visually similar payloads may not match.
- Determine whether the entity uses one availability topic or a list. Home Assistant supports availability modes such as all, any, and latest, and the selected mode changes how multiple topics are evaluated.
- Inspect broker logs for duplicate client identifiers. MQTT brokers commonly replace an existing connection when a second client connects with the same ID, producing a repeating disconnect pattern.
- Check the device’s Last Will, birth message, retain setting, keepalive, and clean-session behavior. Availability faults often survive restarts because a retained offline payload remains valid at the broker.
- Correlate failures across devices. Simultaneous changes point toward broker, network, power, DNS, or host problems; one device family points toward its firmware or configuration.
- Measure Wi-Fi signal and power stability at the device, but do not stop there. A strong signal does not rule out DHCP conflicts, access-point roaming, brownouts, or duplicate credentials.
- Before clearing a retained message, verify the exact topic and understand the publishing tool. A wildcard or wrong topic can disturb many devices.
Failure-pattern examples
- State updates continue while availability is offline: troubleshoot the availability topic and payload separately from the state topic.
- All MQTT devices go unavailable after a broker restart: inspect retained birth/Last Will behavior and reconnection logs before editing every entity.
- One device flips at a fixed interval: compare keepalive, watchdog, DHCP lease, power-save, and scheduled restart timing.
- Two identical devices knock each other offline: assign unique MQTT client IDs and confirm both remain connected simultaneously.
- Multiple availability topics use mode all: one silent auxiliary topic can hold the entity offline even though the primary device is publishing normally.
Advanced notes that prevent false fixes
- Retained messages describe the last retained value, not necessarily the present physical state; publishers must update them correctly.
- QoS affects delivery guarantees but does not repair a semantically wrong availability payload.
- Disabling availability hides the diagnostic signal and should not substitute for fixing reconnections.
- Do not expose an MQTT broker publicly or weaken authentication during troubleshooting.
- Use a narrow topic listener and redact usernames, passwords, tokens, and personally identifying topic components.
- After repair, document topic names, expected payloads, client ID, retain behavior, and broker location.
Final verification checklist
Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.
- The client remains connected longer than the previous failure interval.
- Availability and state topics show expected payloads.
- No duplicate-client disconnect appears in broker logs.
- The entity recovers correctly after one controlled broker restart.
- Other MQTT devices remain unaffected.
- No stale retained offline value reappears.
Official reference
Technical behavior and terminology were checked against Home Assistant MQTT documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.