A container that can't reach the internet is one of those failures that makes you question your whole setup. The app was working fine yesterday. Today, docker compose up gives you a running container, the logs look clean, and yet curl from inside it just hangs until it times out. Nothing changed. Except something obviously did.
I've hit this wall more times than I'd like to admit, on my own projects and on client machines. And the pattern I see over and over is that people reach for docker network prune or a full docker system prune before they know what's actually broken. That's guessing, not debugging. This guide is about how to fix docker container networking issues in a way that doesn't involve blindly restarting everything and hoping. You'll get a symptom-to-cause map, the commands that actually tell you something, and the fixes for the cases that trip up even experienced people.
Key Takeaways
- Most "network not working" reports fall into four buckets: DNS resolution, NAT/masquerade, subnet collisions, and MTU. Diagnose the bucket first, then fix.
- Testing with
pingfrom inside a container tells you very little. Test DNS and port reachability separately. - Subnet overlap with your company VPN or home LAN is the number-one cause of "the container has no internet" on a machine that otherwise works.
- Intermittent drops are usually a full conntrack table or a bridge that got recreated, not a Docker bug.
default-address-poolsindaemon.jsonis the fix you set once and never think about again.
Why is my docker container network not working?
Almost always because one layer of the stack is misconfigured while the others are fine, and the error message doesn't tell you which. A container has four things it needs to talk to the outside world: an IP address on a bridge, a route to the gateway, a working DNS resolver, and NAT on the host. Break any one of them and the symptom looks identical from the outside — silence.
So you diagnose by elimination. The commands below are the ones I run in order, and they take about two minutes total.
Step one: check the bridge
Start at the host. Run docker network ls and confirm the bridge your container is attached to actually exists. Then inspect it:
docker network inspect bridge— look at the subnet and gateway. Is the gateway address set? Is the subnet something sane like172.17.0.0/16?ip addr show docker0on the host — does the bridge interface exist and have the same gateway IP?docker exec -it <container> ip route— does the container have a default route pointing at that gateway?
If the default route is missing, the container has no way out. That usually means it's on a none or a custom network with no gateway defined. Wrong network attachment, wrong fix.
Step two: separate DNS from connectivity
This is the part people skip, and it's the most useful split in the whole diagnosis. Inside the container:
cat /etc/resolv.conf— what nameserver is it using? On a user-defined bridge it should be Docker's embedded resolver at127.0.0.11.ping 8.8.8.8— if this works, the route and NAT are fine, and your problem is DNS.nslookup google.com— if this fails while the ping above succeeded, you've isolated it to DNS with certainty.
If IP connectivity works but names don't resolve, the fix is nearly always a bad /etc/resolv.conf — often a corporate DNS server baked into the host that the container can't reach. Override it with --dns 1.1.1.1 on docker run, or the dns: key in Compose, and re-test.
If neither works — no ping to 8.8.8.8 either — you're looking at NAT or routing on the host. Jump to the IPAM section below, because a subnet collision is the most likely cause.
The one command that tells you the most
When I'm stumped, I run docker run --rm -it --network container:<broken-container> nicolaka/netshoot. It drops a full toolkit into the exact same network namespace as the broken container. From there, tcpdump, dig, mtr, and ss all work. It turns a black box into something you can watch in real time.
The subnet collision nobody checks
Here's the scenario. Your laptop connects to the company VPN. The VPN hands out addresses in 172.17.0.0/16. Docker's default bridge also uses 172.17.0.0/16. You start a container, it gets an IP, and now the host has two different routes claiming the same range. The container can talk to itself. It cannot talk to anything else.
I've watched this cost a team half a day. The container "had no internet," the firewall was blamed, and the actual problem was that the VPN and docker0 were fighting over the same addresses. The symptom is deceptive because it's intermittent — it only breaks when the VPN is up.
Fix it permanently with address pools
Don't fix this one container at a time. Set a range Docker will never hand out, in /etc/docker/daemon.json:
{"default-address-pools": [{"base": "10.201.0.0/16", "size": 24}]}- Restart the daemon:
sudo systemctl restart docker. - Recreate containers so they pick up new addresses.
Pick a base that doesn't overlap your VPN, your home LAN, or the office network. 10.201.0.0/16 is a reasonable choice because it's far outside the ranges most consumer routers and corporate DHCP servers use. Set this once and you'll never debug a subnet collision again.
How do I configure the network for a docker container?
You usually don't need to touch it — the default bridge works for a single container reaching the internet. The moment you have two containers that need to find each other by name, though, you need a user-defined network. The default bridge doesn't do name resolution between containers; a user-defined bridge does.
The practical setup
Create a network and attach your services to it:
docker network create app-net— creates a user-defined bridge with DNS enabled.docker run --network app-net --name db postgresdocker run --network app-net --name api myapp— the app can now reachdbby hostname, no IPs or links needed.
In Compose, this happens automatically: every service in a compose.yaml joins a shared network by default and can reach the others by service name. That's why Compose "just works" and hand-rolled docker run commands don't. If you're hand-rolling and inter-container communication fails, the first thing to check is whether both containers are on the same user-defined network — not two separate ones.
The comparison table
| Network type | Container-to-container DNS | Use when |
|---|---|---|
| Default bridge | No | Single container reaching the internet |
| User-defined bridge | Yes, by name | Multiple services that talk to each other |
| Host | N/A (shares host stack) | You need raw performance and don't care about isolation |
| None | No | Fully isolated batch job |
If name resolution is failing between containers on a user-defined bridge, run docker network inspect app-net and check that both containers are actually listed in the Containers section. A container restarted outside the network won't be there, and you'll wonder why db won't resolve.
Random drops and intermittent failures
The worst kind: the container works, then loses its network after a while. No config change, no redeploy. This is not the same class of problem as the ones above, and the fixes are different.
The conntrack table
Linux tracks active connections in a table. On a busy host, or one with a lot of containers, that table fills up. When it does, new connections get dropped silently — which looks exactly like random network loss. Check it with cat /proc/sys/net/netfilter/nf_conntrack_count and compare it against nf_conntrack_max from the same directory. If the count is sitting at or near the max, that's your culprit. Raise the limit in /etc/sysctl.conf and reload with sysctl -p.
The bridge that vanished
Another cause I've seen: the docker0 bridge or a custom bridge gets recreated — often after a daemon restart or a Docker update — and containers that were started before the restart lose their route. The fix isn't on the network; it's restarting the affected containers so they re-attach. If this happens regularly, check whether something on the host is restarting the Docker daemon (a failing health check, an update timer).
And the reverse-proxy case: nginx in one container proxying to services in others, intermittently failing. Every time I've debugged this, the resolution was to confirm all the proxied services are on the same user-defined network as nginx, and that nginx is reaching them by service name rather than a stale IP that changed after a redeploy.
Why are people moving away from Docker?
They aren't moving away from containers — they're moving away from the Docker daemon as the thing managing them. Docker Desktop's licensing change for large organizations pushed a lot of teams off it, and the practical result is that the daemon that used to run everything on your laptop is now replaced by alternatives like Podman, containerd, or a full on-machine Kubernetes like kind or k3s. Docker the format and Docker Compose are still everywhere. Docker Desktop the app is what people replaced.
Worth knowing if you're debugging networking: those alternatives handle the bridge and DNS slightly differently. Podman runs rootless by default, which changes how port binding and NAT work. If a networking fix that works under Docker does nothing under Podman, that difference is usually why.
How can I fix an unhealthy docker container?
An "unhealthy" status is not a networking diagnosis — it means the container's own HEALTHCHECK is failing. Docker runs the check command on a timer and marks the container unhealthy when it fails repeatedly. The fix is to find out which check is failing and why. Run docker inspect <container> and look at State.Health — the Log array holds the last several check outputs, and they tell you exactly what failed.
If the failing check is a network check — a curl to a health endpoint, a TCP connection to a port — then the underlying problem is one of the network issues above, and the health status is just the messenger. If the check itself is badly written (wrong port, wrong path, too short an interval), fix the HEALTHCHECK definition. I once spent twenty minutes chasing a "network failure" that turned out to be a healthcheck pointed at localhost:8080 when the app was listening on 0.0.0.0:3000. The network was fine. The check was wrong.
The honest conclusion: the container tells you it's broken, but the healthcheck never tells you why. That's what the diagnosis order above is for.
The real skill here isn't memorizing fixes — it's building the habit of isolating layers before touching anything. Route, DNS, NAT, then the container's own config. Nine times out of ten, the fix is sitting in one of those four checks, and you find it in two minutes instead of two hours. The one time it isn't, it's a subnet collision you never would have guessed — which is exactly why you set default-address-pools the day you set up the machine, before the VPN ever gets involved.