Gluetun Troubleshooting: Fix Common Errors

Running into issues? This Gluetun troubleshooting guide covers the most common problems and how to fix them quickly, so you can get back to a protected connection.

Container Won't Start Or Stays Unhealthy

• Confirm you added cap_add: NET_ADMIN — without it the firewall can't be built.
• Double-check your provider name, protocol, and credentials for typos.
• Read the logs; Gluetun prints a clear reason when the tunnel fails to come up.

No Internet In Routed Containers

This is usually the kill switch doing its job before the tunnel is ready:

• Wait for Gluetun to report healthy before expecting connectivity.
• Make sure the child container uses network_mode: "service:gluetun".
• Publish ports on the Gluetun service, not the child container.

DNS Resolution Fails

If names don't resolve, the encrypted DNS server may be blocked on your network. Try switching the DNS-over-TLS provider, or temporarily disable it to isolate the issue.

Port Forwarding Not Working

Only some providers support forwarded ports, and the value can change on reconnect. See our port forwarding guide to wire it up correctly.

Wrapping Up

Most Gluetun issues come down to the NET_ADMIN capability, credentials, or startup timing. Work through these in order and you'll resolve the majority of problems. New here? Our beginner's guide covers setup from scratch.