Interface is up but wg-quick failed: what to do next

The unit is red, the interface exists, and the tunnel mostly works, which is the most confusing combination available. Setup is a sequence: the interface is created first, then addresses, routes, resolver settings and any hook commands follow. A failure at step four leaves the first three in place, so the interface name is evidence that startup began, not that it finished. One extra fact would have saved the confusion: the step that failed.

Partial state is the normal failure

That behaviour is worth expecting rather than treating as corruption. The interface is the cheapest part of setup and the easiest to leave behind, and it is also the part that makes the machine look half-working.

What does not exist yet is whatever came after the failing step. If the failure was at the resolver stage, addresses and routes are present and DNS is not. If it was a route, the tunnel has an address and no path through it.

The consequence is a machine that answers some tests and fails others, which is why people conclude the service is flapping when it never started successfully at all. A service that never finished cannot flap. It can only fail repeatedly for the same reason.

Find the first failing step

Read the journal for the unit rather than the current status alone, and read it from the top of the failed run. The last line tells you the exit code; the first error tells you what to repair.

These commands print the unit state, the boot journal for that unit and the live tunnel state:

systemctl status wg-quick@wg0
journalctl -u wg-quick@wg0 -b --no-pager | tail -40
wg show
ip -4 addr show dev wg0

A resolver error, a route that already exists, a hook that exited nonzero and a configuration parse failure all appear in that window, and each one names its own component. Guessing from the interface state alone ignores all of that information.

Three conditions that decide the repair

Decide whether you are cleaning up, repairing in place or removing the unit from the boot path, and decide it before typing anything.

If the interface is broken but the configuration is correct, clean up and start again. If the configuration is wrong, fix it and still clean up first, because starting a second manager over partial state produces two owners for one interface. If the failure is a missing system component such as a resolver helper the machine does not have, install or remove the dependency deliberately rather than editing the unit until it stops complaining.

Those three cases cover most of what looks like a mysterious red unit. The distinguishing question is whether the same failure would occur on a machine with a clean state, and the answer usually comes from the first error line.

Clean up before you retry

A retry over existing state can fail for a new reason and hide the original one. Bring the interface down through the same tool that created it, then confirm nothing is left.

Do not delete unrelated interfaces and do not reset the host networking stack. Both are large actions taken to fix a small object, and they turn a single failed tunnel into a machine whose other connections need re-establishing. The correct scope is one interface and the unit that owns it. Anything wider needs a reason written down before it happens.

Prove the tunnel, not the unit

A green unit means the startup sequence exited zero. It does not mean a packet reached the other side, and it does not mean the resolver was set the way you intended.

Send a request through the tunnel and read the state that produced it:

systemctl is-active wg-quick@wg0
wg show wg0 latest-handshakes
ping -c 3 10.63.0.1
resolvectl query internal.example.net

A handshake with no reply still tells you the tunnel formed and the far side is quiet, which is a different problem from a unit that never started. Keep the unit state, the handshake and the request result in one record, because they fail independently and only the combination describes the system.