wg-quick Breaks DNS on Connect: Read the Setup Error

The tunnel comes up, the handshake completes, and name resolution stops. Nothing in the peer configuration changed, because the DNS line was never part of the peer configuration. It belongs to the setup helper, which means the failure lives in the host's resolver tooling rather than in WireGuard's keys.

Read the first message the helper printed, not the last one, and the difference between a missing utility and an unreachable server becomes obvious.

The DNS line is a helper feature

The core configuration fields describe peers, keys and allowed addresses. Resolution is added on top by whichever script brings the interface up, and each implementation does it differently. A desktop client may manage DNS through its own service, a distribution script may call one of several resolver utilities, and a container may do neither. The configuration file cannot tell you which of those paths is in play.

That is why a configuration file can be valid for the protocol and still fail during setup: the failure belongs to a hook the protocol never sees.

Writing an extended field into a core configuration and expecting the protocol tool to accept it produces the same confusion from the other direction. The two parsers read different files.

Knowing which one is running is the first diagnostic step, and it is usually visible in the command you typed rather than in the configuration file.

Read the first error the helper prints

Bring the interface up in the foreground and read the output in order. A missing resolver utility, a failed hook and an unreachable server all stop the same command at different points, and each has a different repair.

wg-quick up wg0
resolvectl status wg0
ip route get 10.66.0.1

The first command reports setup progress, the second shows which servers the interface now claims, and the third shows whether the resolver address is actually reachable through the tunnel. A resolver that is configured but unroutable produces timeouts rather than configuration errors, which is why the two checks belong together. Reading only the status output produces a confident and wrong conclusion.

If setup completed and resolution still fails, compare the resolver the helper installed with the one the network was using before. A private resolver needs a route through the tunnel, and a configuration that lists it without covering its prefix leaves every query waiting.

Which resolver the host actually has

Modern Linux hosts frequently run a local stub resolver, so the address the helper installs is consumed by that stub rather than by applications directly. Editing a generated file by hand can appear to work until the next reconnect, when the helper rewrites it.

Use the supported integration for the distribution and let one component own the resolver state. Two owners produce the same race as two owners of an interface address, and the symptom is a host that resolves correctly for a few minutes after each change.

Internal names deserve their own check. A public resolver can restore general browsing while making every corporate name fail, which is the opposite of what the tunnel was for. Query the internal name against the intended server before concluding that DNS is fixed.

Cleanup matters as much as setup

Bring the interface down and inspect the resolver state again. A helper that restores the previous configuration leaves the host usable; one that leaves its own servers behind creates the next failure, often hours later when the tunnel is long gone.

Stale state is easy to spot once you look for it. A resolver list can point at an address on an interface that no longer exists, and a search domain can survive a network you left this morning. Either one makes the next connection behave unpredictably, and neither appears in the tunnel's own status output. The check takes ten seconds and saves the next person an hour.

Keep the diagnostic separate from the repair. If every destination fails rather than just name lookups, routes and forwarding are the suspects and the DNS line is a distraction. The wg-quick manual documents which fields it handles and which belong to the protocol, and that boundary is the whole answer to most of these reports.