Boundary
Home Assistant to service, or service to device layer.
Home Assistant cannot reach a broker or required service
Use this flow when Home Assistant reports a broker, integration host, or local service unavailable. It separates Home Assistant-to-service reachability from service-to-device problems.
Security first: do not paste broker passwords, client certificates, private keys, or tokens; do not expose MQTT/Home Assistant to the internet or disable TLS validation as a shortcut.
What this flow is for
Home Assistant cannot reach a broker, integration host, or local service. The first split is whether Home Assistant can reach the service at all or the service can reach its devices.
First safe checks
- Record integration/broker, exact redacted error, host/port role, and last known-good time.
- Check Home Assistant health and target-host power/reachability on the intended local network.
- Verify hostname/IP, port, time/date, network segment, and recent firewall/host changes.
- For MQTT, record connection, certificate, and availability state without exposing credentials.
- Capture diagnostics/logs before a clean integration reload.
Best evidence
Capture this before changing configuration
Connection
Integration/broker, host/port role, exact redacted error, and last known-good time.
Change history
Recent host, IP, port, firewall, certificate, network, or integration changes.
Likely causes
Most likely problem buckets
Host or broker unreachable
The target service is stopped, powered off, or unreachable on the intended local network.
Network or port state
Hostname/IP, port, firewall, segment, or time/date no longer matches.
TLS or authentication
Certificate/hostname validation or client configuration prevents a secure connection.
Stale integration state
Discovery or availability state is stale after a restart or broker change.
Next safe steps
Take one step at a time
ACT-AUTO-010
Capture integration/broker, redacted error, host/port role, and last known-good time.
ACT-AUTO-011
Verify Home Assistant health, target reachability, host/port, time/date, and recent network changes.
ACT-AUTO-012
Inspect documented connection/diagnostics state and capture logs before a clean reload.
ACT-AUTO-013
Hand off TLS, broker auth, firewall, network-segment, or repeated discovery failures.
Best follow-up ask
Is the failure between Home Assistant and a local broker/host, or between that service and the device layer?
When to stop and hand off
Escalate when the fix would require credentials, certificate/private-key work, firewall changes, public exposure, or weakening validation.
Source provenance
Reviewed against official Home Assistant guidance
This vendor-neutral flow uses Home Assistant's MQTT configuration and troubleshooting guidance. Deployment-specific broker, TLS, host, and network changes still require an authorized operator.
Map the smart-home service
Record the hub, broker, host, integration, network relationship, and redacted diagnostics privately.
Open private discoveryContinue in support chat
The support assistant can ask the next safe question without accepting credentials or private keys.
Open support chat