Home Assistant Companion App cannot connect: internal URL, HTTPS, Wi-Fi, and certificate fixes

Direct answer: First decide whether the app fails only at home, only away from home, or everywhere. A home-only failure points to the internal URL, Wi-Fi isolation, local-network permission, DNS, or router behavior. An away-only failure points to the external URL, remote-access service, firewall, DNS, or TLS certificate. Failure everywhere usually means the Home Assistant server is down, the saved URL is wrong, or authentication must be reset.

This guide covers the official Android and iOS Home Assistant Companion Apps. It assumes the Home Assistant web interface can be tested from at least one browser. It does not recommend exposing port 8123 directly to the internet.

Symptoms and affected scope

• The app displays “Unable to connect to Home Assistant.”
• The app works on mobile data but not home Wi-Fi, or works on Wi-Fi but not mobile data.
• A certificate, hostname, timeout, or connection-refused message appears.
• Notifications arrive but dashboards do not load.
• The browser works while the app fails, or the reverse.

These symptoms can look similar even though their causes sit in different layers. The safest approach is to preserve the current working state, identify the first failing layer, and change one variable at a time. This prevents a recoverable Home Assistant Companion App cannot connect problem from turning into lost pairings, lost entities, or an inaccessible installation.

Ranked likely causes

• 1. The saved internal or external URL is wrong, includes the wrong port, or points to an old hostname.
• 2. iOS local-network access is denied, Android network restrictions are active, or the phone is on a guest VLAN.
• 3. Hairpin NAT or split DNS is missing, so an external hostname cannot loop back from the home network.
• 4. The HTTPS certificate is expired, incomplete, self-signed, or issued for a different hostname.
• 5. A reverse proxy, firewall, VPN, Private DNS, content filter, or ad blocker interrupts the WebSocket connection.
• 6. The server is unavailable, restarting, or reachable only from another subnet.

Before changing anything

Make a current backup, record versions and installation type, capture the exact first error, and remove secrets from any notes. Do not delete integrations, reset devices, erase databases, or reflash firmware as an opening move. If equipment is hot, swollen, wet, arcing, smoking, or connected to mains wiring that must be opened, stop and use qualified help.

Least-destructive diagnostic order

1. 1. From a browser on the same phone and network, open the exact URL saved in the app. Record whether DNS fails, the connection times out, the certificate is rejected, or the login page appears. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
2. 2. Test the same URL once on Wi-Fi and once on mobile data. This two-path test is more useful than reinstalling the app because it identifies which side of the route is failing. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
3. 3. Open the app’s server connection settings and inspect the Home Assistant URL. Use a complete URL with https:// when TLS is configured. If external port 443 forwards to the Home Assistant service through a proxy, do not append :8123 to the public hostname. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
4. 4. On iOS, verify Settings → Apps → Home Assistant → Local Network is enabled. On Android, remove battery or data restrictions only when they are actually blocking the app; do not grant unrelated permissions. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
5. 5. If local access fails, confirm the phone is not on a guest network and that client isolation is disabled for the trusted home SSID. Test the Home Assistant host’s local address from another trusted device. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
6. 6. If the public hostname works outside but not inside, configure supported split DNS or router NAT loopback. Do not weaken TLS verification or replace the hostname with a private address while away from home. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
7. 7. Inspect the certificate in a browser. Confirm it is current, covers the exact hostname, and provides a complete chain. A browser exception is not an acceptable permanent fix for an app that sends authentication tokens. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
8. 8. If a reverse proxy is used, verify WebSocket forwarding and the Home Assistant trusted-proxy configuration. A normal login page can load while the persistent app connection still fails. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
9. 9. Disable VPN, Private DNS, filtering, or security apps temporarily one at a time for diagnosis. Restore each control after the test. Do not leave protective controls disabled. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.
10. 10. Before resetting app data, back up notification-related settings and verify the Home Assistant user credentials. Reset the connection only after URL, network, and TLS tests identify the app state as the remaining cause. After this step, stop and interpret the result before moving on. A positive result narrows the fault to this layer; a negative result preserves the current configuration and justifies the next check.

Choose the correct branch

• Works on cellular only: focus on local-network permission, guest Wi-Fi, split DNS, and NAT loopback.
• Works on Wi-Fi only: focus on the external hostname, remote-access service, router forwarding, TLS, and carrier/VPN filtering.
• Browser works, app fails: compare the exact saved URL, app permissions, certificate trust, and stale authentication state.
• Neither browser nor app works: troubleshoot server availability and routing before changing the app.

How to interpret the results

If the evidence points to the saved internal or external URL is wrong, includes the wrong port, or points to an old hostname. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to iOS local-network access is denied, Android network restrictions are active, or the phone is on a guest VLAN. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to hairpin NAT or split DNS is missing, so an external hostname cannot loop back from the home network. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the HTTPS certificate is expired, incomplete, self-signed, or issued for a different hostname. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to a reverse proxy, firewall, VPN, Private DNS, content filter, or ad blocker interrupts the WebSocket connection. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

If the evidence points to the server is unavailable, restarting, or reachable only from another subnet. Correct only that layer, then repeat the smallest relevant test. If the result does not change, restore the prior value and continue; do not stack speculative fixes.

Verified repair and final checks

Verify dashboard loading, entity updates, a fresh app launch, one Wi-Fi-to-cellular transition, and a notification round trip. Confirm that the connection uses the intended HTTPS hostname and that no certificate warning was bypassed.

A repair is not verified merely because an error banner disappears. Confirm the underlying connection or service, observe fresh state data, and test after a controlled restart where appropriate. Keep the previous configuration until the new state has remained stable.

Rollback and recovery

If a URL edit makes the app worse, restore the recorded prior URL. If proxy changes fail, restore the last known configuration and restart only the proxy. Keep a browser session open during changes so you do not lock yourself out.

Write down each change before making it. Reversibility matters: a documented URL, service setting, serial path, integration state, or firmware version is much easier to restore than a configuration changed in several places at once.

Prevention

Use one documented external hostname, valid automated TLS renewal, supported remote access, stable internal DNS, and a trusted non-guest Wi-Fi network. Record the internal and external paths before changing routers.

Review this setup after platform, firmware, router, certificate, or host changes. Backups should exist off the device and should be periodically checked for visibility and required encryption material.

Privacy and safety

Never publish access tokens, API keys, encryption keys, Wi-Fi credentials, public IP addresses, precise locations, camera URLs, door-lock states, alarm details, or complete unsanitized diagnostics. Do not weaken TLS, firewall rules, authentication, or network isolation simply to make an error disappear.

Testing disclosure

This guide is based on the current official documentation and linked upstream reports. Troubliq did not physically test every device, adapter, network, phone, host, or installation variant described. Device-specific behavior can differ; preserve backups and follow the manufacturer’s safety instructions.

Sources

• Companion App networking
• Companion App errors
• Connection security level
• HTTP integration and reverse proxies

Last reviewed: September 24, 2026.

Next: use the Home Assistant Error Decoder to match the exact message, or return to the current Home Assistant problems hub.

Detailed diagnostic reference

Build a four-path test

Test the saved URL from the phone on home Wi-Fi, the same phone on cellular, another device on home Wi-Fi, and an external browser. This matrix separates app state from server state, and local routing from public routing, without reinstalling anything.

Interpret DNS failures

A hostname-not-found response means the device cannot resolve the name. Compare the phone’s DNS provider, VPN, Private DNS, router DNS, and split-DNS record. Do not replace a public HTTPS hostname with an insecure numeric address as a permanent workaround.

Interpret timeouts and refusals

A timeout usually indicates filtering, routing, or an unreachable host. Connection refused means the address answered but nothing accepted the requested port. These outcomes require different checks; neither is fixed by clearing the app cache.

Check WebSocket behavior

Home Assistant uses a persistent WebSocket after the initial page loads. A proxy may serve the login screen correctly while failing to upgrade the connection. Review the proxy’s WebSocket forwarding and timeout configuration using its official documentation.

Validate TLS completely

Confirm the certificate covers the exact hostname, is within its validity dates, and supplies the intermediate chain. Test renewal before expiration. Never install an unknown root certificate or turn off certificate validation merely to silence the app.

Handle split DNS safely

When the public hostname cannot loop back through the router, configure a local DNS record that returns the internal proxy address while preserving the same HTTPS hostname. This avoids maintaining different identities and keeps certificate verification meaningful.

Review phone permissions narrowly

Local Network permission on iOS is directly relevant. Location permission may affect SSID-based internal URL selection, but it should be granted only when that feature is used. Avoid granting contacts, microphone, or unrelated permissions to solve a network error.

Reset only the affected layer

If network and browser tests pass, remove and re-add only the saved server connection or reset the app according to official guidance. Record notification settings and device name first so duplicate mobile_app entities can be identified safely.

Remote-access safety

Prefer Home Assistant Cloud, a properly configured reverse proxy, or a secure VPN. Do not expose the default service directly without TLS and access controls. Rate limits and strong unique credentials protect the login but do not replace safe network design.

Completion criteria

The app should open from a cold start, update entities, switch between Wi-Fi and cellular, reconnect after screen lock, and receive a fresh notification. Verify that all paths use the intended hostname and no certificate exception remains.