How to Test Whether DNS Is Causing Immich Connection Failures
DNS is a likely Immich culprit only when the failing client cannot turn the exact Immich hostname into the address that should serve it, or when that answer changes across resolvers, networks, or time.
Test name resolution separately from application reachability. A successful IP-level connection can show that a route and port exist, but it does not prove HTTPS, reverse-proxy routing, certificates, or host-based rules will work without the hostname. The safest workflow records the exact failing name, queries it from the affected client, compares resolvers, then repeats the original Immich action after one DNS-layer change.
Define the Exact Hostname and Failure Path
Record the hostname the failing Immich client actually uses, the network it is on, the time of failure, and whether the failure affects the web app, mobile app, or both. Do not begin with a generic test such as resolving an unrelated public domain, because that only proves some DNS path works.
Compare the same hostname from a working client and the failing client. Record every A and AAAA answer, the resolver that replied, and whether the client is inside the home network, on mobile data, or behind a VPN. Different answers may be intentional with split DNS, but they must still lead each client to a reachable endpoint.
As a control, test whether the expected server address and port are reachable without relying on the normal DNS lookup. Treat this only as a network-path discriminator: HTTPS certificates, SNI, reverse proxies, and virtual hosts can still reject an IP-based request even when the service is healthy.
Query DNS From the Failing Client, Not Only the Server
Run a DNS query on the device or environment that is actually failing. If the Immich client is behind a VPN, private DNS profile, container stub, or router-provided resolver, a query from the server itself may use a different resolver path and can hide the problem.
Query the failing hostname through the client’s default resolver first, then query a known comparison resolver or the intended internal resolver explicitly. A targeted dig query exposes the returned answer, responding server, status, and query time so you can see whether the failure follows one resolver.
Repeat the query several times instead of trusting one success. Record NXDOMAIN, SERVFAIL, timeouts, stale addresses, or inconsistent A/AAAA answers. A stable correct answer shifts suspicion away from basic DNS resolution and toward routing, proxy, TLS, firewall, or application configuration.
Compare Resolver Results and Error Types
Interpret the response code before changing settings. NXDOMAIN means the queried name does not exist from that resolver’s view; SERVFAIL means resolution could not be completed; a timeout means the resolver did not answer in time. A syntactically successful answer can still be wrong if it points at an old router address or unreachable endpoint.
Name-not-found failures and temporary resolver failures are different branches. Use name-resolution error differences to decide whether to fix a missing record, an unreachable resolver, or an unstable DNS path instead of treating every lookup failure as the same problem.
If only the home resolver returns the old or wrong address while another resolver returns the intended public value, inspect local overrides, split-DNS records, DHCP-provided DNS, filtering services, and caches. If every resolver returns the same correct address, stop changing DNS and move to the service path.
Use a Controlled Bypass to Prove or Reject DNS
Create one temporary, reversible control that changes only name resolution for the failing client. For example, query a different resolver directly or use a temporary hosts-file entry that maps the exact Immich hostname to the known intended endpoint. Preserve the original settings so the test can be undone immediately.
If the original Immich workflow starts working while the hostname stays identical and only its resolution path changed, DNS is strongly implicated. If the same hostname still fails after it resolves to the verified endpoint, the fault is downstream of DNS and you should inspect proxy routing, certificates, NAT, firewall rules, or the Immich service itself.
If one clean query cannot reproduce the household failure window, compare host, container, local resolver, upstream resolver, DHCP, VPN, and cache state over time. A multi-layer DNS failure check helps catch intermittent cases that disappear during a one-time test.
Clear the Right Cache and Re-Test the Original Immich Workflow
After correcting a DNS record, resolver, DHCP option, split-DNS rule, or local override, clear only the relevant client or resolver cache when practical. Do not repeatedly flush every layer without recording what changed, because that can make a transient success impossible to explain.
Resolve the hostname again from the affected client and verify the intended A/AAAA answer, resolver, and response time. Then open Immich through its normal hostname, load older assets, search, and perform one safe upload or other write action so the test covers more than a login page.
Repeat the check from the network state that originally failed, such as mobile data, home Wi-Fi, VPN-connected Wi-Fi, or after a router/DHCP renewal. DNS is cleared as the root cause only when the normal hostname remains correct through the trigger that previously broke it; otherwise preserve the new evidence and continue at the next network layer.
Recommended products
Support & Tips
More to Read
How to Optimize Immich Database Connections for Concurrent Containers
Do not raise max_connections first. Measure Immich sessions, total every container's demand, preserve admin headroom, and tune only the proven bottleneck.
How to Prevent Duplicate Jobs or Imports in Immich
Separate repeated jobs from duplicate assets. Use one canonical ingestion path, control retries and path changes, then test re-entry on a small cohort.
How to Repair Immich After Its Database Volume Fills Up
Never delete PostgreSQL WAL to free space. Stop Immich writes, preserve database state, add safe capacity, recover PostgreSQL, then prevent recurrence.
