ESPHome / Troubleshooting
ESPHome Device Is Online but Unavailable in Home Assistant
When an ESPHome device is on the network but Home Assistant cannot use it, separate endpoint identity, reachability from the HA runtime, native API port 6053, encryption, and runtime stability before reflashing.
By Andrey Tretyak · Sources last reviewed
Home Assistant integrates with ESPHome devices directly through the native ESPHome API and maintains a persistent connection. Wi-Fi or ping reachability alone does not prove that this API connection is healthy.[3][1]
ESPHome's native API uses TCP port 6053 by default and can use a 32-byte base64 pre-shared encryption key. An endpoint or encryption mismatch can therefore break Home Assistant while the device itself remains online.[1][3]
Sections
Applicability
Symptoms
Quick diagnosis
Separate device network presence from the Home Assistant native API path: identity, reachability, TCP 6053, handshake evidence, then runtime stability.
Record the current device IP/hostname and HA endpoint
Compare the actual ESPHome device identity with the endpoint Home Assistant is trying to use before changing firmware or keys.[3][1]
Test the native API path from the Home Assistant runtime
Check whether the Home Assistant host/container can reach the device and its configured native API port. A browser or ESPHome dashboard test from another machine does not prove this path.[3][1]
Read Home Assistant and ESPHome connection logs
Use the connection evidence to distinguish endpoint/network failure from an encryption mismatch or unstable device runtime.[3][1]
Interactive troubleshooter
Your answers stay in this browser tab. The tool does not connect to your systems or send diagnostic results.
Guided check / step 1
Is the ESPHome device on the network while Home Assistant shows it unavailable?
This page targets an online device with a failed Home Assistant native API path.[3][1]
Read the complete diagnostic tree without using the controls
- Is the ESPHome device on the network while Home Assistant shows it unavailable?
This page targets an online device with a failed Home Assistant native API path.[3][1]
- Yes — device is online → Does Home Assistant point to the current identity/IP of the intended device?
- No — device itself is offline → Use an offline-device diagnosis
- Does Home Assistant point to the current identity/IP of the intended device?
Prove endpoint identity before testing keys or firmware.[3][1]
- Yes — endpoint matches → Can the Home Assistant runtime reach the device on the LAN?
- No — endpoint is stale or wrong → The integration endpoint is stale or wrong
- Can the Home Assistant runtime reach the device on the LAN?
Test from the Home Assistant host/container context, not only from another client.[3]
- Yes — LAN path works → Is the configured ESPHome native API TCP endpoint reachable?
- No — HA runtime cannot reach it → The Home Assistant runtime cannot reach the device
- Is the configured ESPHome native API TCP endpoint reachable?
The native API uses TCP port 6053 by default unless configured otherwise.[1]
- Yes — API TCP endpoint is reachable → What do the native API connection logs show?
- No — API endpoint is blocked/unavailable → The native API endpoint is not reachable
- What do the native API connection logs show?
Once TCP is proven, use handshake evidence instead of repeating the listener test.[1][3]
- Encryption/key mismatch → The native API encryption identity does not match
- Another specific API error → A different native API error is present
- No clear API error → Is the device rebooting or otherwise unable to keep a stable API connection?
- Is the device rebooting or otherwise unable to keep a stable API connection?
Home Assistant maintains a persistent native API connection and automatically reconnects when it is lost.[3]
- Yes — runtime is unstable → Device runtime instability is breaking the persistent API connection
- No — runtime looks stable → The native API outage is not yet isolated
- Use an offline-device diagnosis
If the device itself is off the network, the native API path is not the first failing layer.[3]
- The integration endpoint is stale or wrong
Correct only the proven endpoint after preserving the current settings.[3]
- The Home Assistant runtime cannot reach the device
Repair the local network path before changing ESPHome API encryption or firmware.[3][1]
- The native API endpoint is not reachable
Keep higher-level key and firmware changes out until the configured API endpoint is reachable.[1]
- The native API encryption identity does not match
Make both sides agree on the intended key; do not disable encryption as a shortcut.[1][3]
- A different native API error is present
Use the exact logged API error and preserve current configuration before another change.[1][3]
- Device runtime instability is breaking the persistent API connection
Investigate the device's own reboot/runtime evidence before changing Home Assistant.[3]
- The native API outage is not yet isolated
Preserve endpoint, network, API, encryption, and runtime evidence for the next investigation.[1][3]
Detailed diagnosis
1. Verify the endpoint identity
Confirm the current IP/hostname belongs to the expected device and that Home Assistant is not targeting an old address or wrong hostname.[3][1]
2. Prove reachability from the Home Assistant runtime
Test from the same host/container context that runs Home Assistant. If that path fails, stop before changing ESPHome encryption or firmware.[3]
3. Check the native API TCP endpoint
ESPHome documents port 6053 as the default native API port unless changed in configuration. Prove that endpoint before interpreting higher-level handshake errors.[1]
4. Classify the API connection evidence
If TCP works, read Home Assistant and ESPHome logs for encryption/key or other native API handshake evidence. Do not use a firmware reflash as a probe.[1][3]
5. Check device runtime stability
A device can appear intermittently online while rebooting or failing to keep the persistent native API connection. Correlate uptime/log evidence before changing the integration.[3][1]
Supported scenarios
These observations narrow the native API failure; they do not justify reflashing or disabling encryption.
Home Assistant is targeting a stale or wrong endpoint
A changed IP or hostname can leave the device online while Home Assistant attempts the native API connection at the wrong endpoint.[3][1]
How to check: Compare the current device identity with the integration endpoint before any reconfiguration.[3][1]
The native API path is not reachable from Home Assistant
The ESPHome dashboard or ping from another machine does not prove that the Home Assistant runtime can reach the device's native API endpoint.[3][1]
How to check: Test the path from the Home Assistant runtime and the configured API port.[3][1]
The native API encryption key does not match
ESPHome's native API supports a 32-byte base64 encryption key; a mismatch prevents a valid API session even when TCP connectivity exists.[1][3]
How to check: Compare the configured encryption identity only after the endpoint and TCP path are proven.[1][3]
Next actions and procedure boundaries
Correct only a proven stale ESPHome endpoint
Before changing anything
- Risk
- Changing the integration endpoint can interrupt the existing connection and may target the wrong device if identity was not proved first.[3]
- Safer check
- Record the current integration endpoint, device identity, and working LAN address before editing.[3]
- Expected result
- Home Assistant reconnects to the same intended ESPHome device through the native API.[3]
- Backup / recovery access
- Record the existing endpoint and ESPHome network identity so the prior state can be restored.[3]
- Rollback
- Restore the previous endpoint if the change does not reconnect the intended device.[3]
If evidence proves Home Assistant points to an old IP/hostname, update only that integration endpoint and retest the native API connection.[3]
Correct a proven native API encryption-key mismatch
Before changing anything
- Risk
- Changing the native API encryption key breaks connectivity until both sides use the same key.[1][3]
- Safer check
- Preserve the current ESPHome configuration and Home Assistant integration settings before changing the key.[1][3]
- Expected result
- The native API handshake succeeds and Home Assistant re-establishes its persistent connection.[1][3]
- Backup / recovery access
- Keep a restorable copy of the existing ESPHome YAML and previous integration settings in a secure location.[1][3]
- Rollback
- Restore the previous key/configuration if the intended device does not reconnect.[1][3]
Only when connection evidence proves the key is wrong, make Home Assistant and the device configuration agree on the intended encryption key. Do not disable encryption as a shortcut.[1][3]
If the HA runtime cannot reach the API, keep firmware and encryption unchanged
Repair the proven network, DNS, VLAN, or firewall path outside this page. Do not reflash the device, disable encryption, or expose port 6053 to the Internet merely because Home Assistant cannot connect.[3][1]
Warnings and boundaries
Editorial verification
The citations beside technical claims show their evidence. HomeLabFix chooses the diagnostic order and states where the evidence stops supporting a conclusion.
- Author and technical editor
- Andrey Tretyak
- Verification basis
- The cited vendor or project documentation plus the page-specific reasoning above.
- Hands-on status
- Direct reproduction is claimed only when a page explicitly describes the tested environment and result. “Last verified” means the cited evidence was reviewed on that date; it does not mean every procedure was reproduced.
- Correction path
- Report a source change, scope error, or reproducible contradiction.
Sources
Links were reviewed on 2026-09-09. Reachability and automated validation do not replace editorial verification of each claim.
- ESPHome Native API Component
ESPHome project · Tier A · accessed 2026-09-09 - ESPHome releases
ESPHome project · Tier B · accessed 2026-09-09 - ESPHome integration
Open Home Foundation · Tier A · accessed 2026-09-09