How to Test Whether DNS Is Causing Home Assistant Connection Failures

Eva Wong

IceWhale author

Eva Wong is the Technical Writer and resident tinkerer at ZimaSpace. A lifelong geek with a passion for homelabs and open-source software, she specializes in translating complex technical concepts into accessible, hands-on guides. Eva believes that self-hosting should be fun, not intimidating. Through her tutorials, she empowers the community to demystify hardware setups, from building their first NAS to mastering Docker containers.

How to Test Whether DNS Is Causing Home Assistant Connection Failures

DNS is a strong suspect when Home Assistant can reach a service by IP address but fails by hostname, when errors explicitly mention name resolution or DNS timeouts, or when the same hostname behaves differently from different networks. It is not proven by a generic “connection failed” message alone.

Test DNS from the machine and network path that actually fails. A laptop resolving a hostname correctly does not prove that the Home Assistant host, container, mobile app, or local resolver sees the same answer.

Start With the Exact Hostname Named in the Error

Read the Home Assistant log or Companion error and write down the exact hostname, not just the integration name. A connection refusal, TLS error, timeout, and DNS lookup failure belong to different layers.

Home Assistant's current connection guidance says that routers, DNS, DHCP, unreachable devices, and unavailable services are common causes of connection errors. The log wording should narrow which branch to test next.

If the error already says “name or service not known,” “temporary failure in name resolution,” or a DNS timeout, move directly to resolver testing. If it says “connection refused,” DNS may already have succeeded and the remote service or port is the better suspect.

Run DNS Tests From the Affected Home Assistant Path

Use dig or nslookup from the Home Assistant host, container, or another system using the same resolver. Compare the returned addresses with what you expect the hostname to represent.

The Companion troubleshooting guide recommends using dig and nslookup when Home Assistant reports a timeout while looking up a hostname. A failed lookup from the affected machine is much stronger evidence than a successful lookup from a different client.

Repeat the test several times if the failure is intermittent. A resolver that succeeds once and times out every tenth request can still create unreliable integrations.

Compare Hostname Reachability With Direct IP Reachability

When safe and meaningful for the service, test the destination by its known IP address. If the IP path works repeatedly while the hostname path fails, the evidence points toward DNS or hostname-specific routing.

Do not treat this as absolute proof for HTTPS or virtual-hosted services. TLS certificates, reverse proxies, and Host headers may require the hostname even when the underlying IP is reachable.

The ZimaSpace guide to intermittent DNS failures in self-hosted applications extends this test by separating resolver latency, stale answers, split DNS, and container-specific resolver paths.

Featured

ZimaCube 2 Personal Cloud Home NAS

ZimaCube2

Check Both A and AAAA Answers

A hostname can resolve successfully and still choose an unusable address family. For example, an AAAA record may exist while IPv6 routing is broken, causing long waits before fallback to IPv4.

Home Assistant's DNS diagnostics explicitly call out DNS server failures and incorrect handling of A and AAAA requests. On Home Assistant OS, the same diagnostics expose resolver health and fallback-DNS options.

Compare A and AAAA results separately, then test connectivity over the returned address family. Do not globally disable IPv6 merely because one hostname is broken; prove the failing path first.

Compare Internal and External DNS When Failure Depends on Location

If a Home Assistant hostname works on mobile data but not on home Wi-Fi, or works inside the LAN but not remotely, compare the DNS answer from both locations. Split DNS may intentionally return a private address inside and a public or tunnel address outside.

Check router DNS overrides, Pi-hole or AdGuard rewrites, mDNS names, local search domains, public DNS records, and stale caches. A correct public record cannot repair a wrong internal override, and a correct LAN record cannot make a private address reachable from the internet.

Change one resolver variable at a time. A temporary public resolver can be a useful diagnostic for public names, but hard-coding public DNS is not a fix when the hostname is supposed to resolve to a private local service.

FAQ

If Home Assistant works by IP but not hostname, is DNS definitely the problem?

It is strong evidence, but not absolute proof. HTTPS certificates, reverse proxies, virtual hosts, and routing rules can behave differently when you bypass the hostname. Confirm the DNS answer and the application path together.

Should I permanently switch Home Assistant to 8.8.8.8 or 1.1.1.1?

Not automatically. Public resolvers are useful for testing public names, but they cannot resolve private split-DNS records unless those records are intentionally published elsewhere. Fix the resolver that should be authoritative for the failing name.