MTU Problems in Container Networks (and How to Fix Them)
Small pings work but big transfers hang. How to confirm an MTU black hole with do-not-fragment probing, where Docker sets MTU, and the fixes that hold up.
Published on • November 19, 2026
AI Assistant

The strangest network bug you will ever debug has a signature: ping works, small HTTP requests work, the DNS handshake completes — and then git clone, scp, or the TLS handshake for a large certificate chain just stops. Nothing is refused, nothing times out cleanly, the connection sits half-open until something gives up. Nine times out of ten that is an MTU problem: packets above a certain size are being dropped somewhere on the path, and because those drops happen to packets with the don’t-fragment bit set, the sender never hears about it.
The symptom table
| Symptom | Why it points at MTU |
|---|---|
ping -c 2 host works, large pings hang | ICMP echo is small; payload size is the variable |
| TLS handshake stalls on some servers | Bigger certificates/chain = bigger records |
scp/rsync/FTP freezes; small HTTP fine | Bulk transfers push full-size segments |
| Works on office LAN, fails over VPN | Tunnel encapsulation shrank the effective MTU |
| Intermittent: some destinations fine | Path MTU differs per destination |
Probing for the black hole
The test is do-not-fragment probing from inside the container. ICMP payload of 1472 bytes plus the 28-byte IP/ICMP header equals a 1500-byte packet — the standard Ethernet MTU:
docker exec api ping -M do -s 1472 -c 2 1.1.1.1 # should work on a 1500 path
docker exec api ping -M do -s 1400 -c 2 1.1.1.1 # binary-search downward until replies return
-M do sets don’t-fragment; if replies stop at some size and resume below it, you have found the path MTU. tracepath shows the same thing with less ceremony when iputils or tracepath is available in the image:
docker exec api tracepath -n 1.1.1.1
1?: [LOCALHOST] pmtu 1450
1: 172.20.0.1 0.063ms
1?: [LOCALHOST] pmtu 1420
Run the probe from inside the container toward the failing destination. Note that on Docker Desktop the host cannot even route pings to Linux containers (a documented Desktop limitation), so probing from the host tells you nothing — test from inside.
Where a container’s MTU comes from
Docker does not invent an MTU per packet; it sets one on the interface it creates, and that value comes from a handful of documented places:
| Source | Scope | How to set it |
|---|---|---|
| Default bridge | dockerd --mtu (default 1500), daemon.json "mtu" | Daemon restart; default bridge only |
| Any bridge network | -o com.docker.network.driver.mtu=<n> | At docker network create time |
| New networks by default | dockerd --default-network-opt bridge=com.docker.network.driver.mtu=1234 (or daemon.json default-network-opts) | Daemon config; existing networks unaffected |
| Overlay (swarm) | Underlay capacity minus encapsulation; control plane via --network-control-plane-mtu (default 1500) | Daemon flag / network option |
| macvlan / ipvlan | Inherits the parent interface’s MTU | Change the parent, or create the subinterface yourself |
Two corrections to folklore you will find repeated online, both verified against docker run --help and docker network create --help on Docker 29.x: there is no --mtu flag on docker network create (the driver option is the way), and there is no docker run --network-optimization flag — do not go looking for it.
Also remember that changing daemon configuration does not affect pre-existing networks. If you fix "mtu" in daemon.json and the broken network was created last month, nothing changes until you recreate that network with the option:
docker network create -o com.docker.network.driver.mtu=1400 app-net-1400
docker network connect app-net-1400 api
Confirm what a network actually carries:
docker network inspect app-net --format '{{json .Options}}' | jq -r '.["com.docker.network.driver.mtu"] // "unset (driver default)"'
docker exec api ip link show eth0
4: eth0@if65: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1400 qdisc noqueue state UP
Why 1400? Encapsulation math
Every tunnel you put in front of containers eats header space that the container never sees. VXLAN — what Docker overlay networks ride on — adds exactly 50 bytes: 14 (Ethernet) + 20 (IPv4) + 8 (UDP) + 8 (VXLAN). So an overlay on a 1500-byte underlay should run containers at 1450, which is the familiar “underlay − 50” rule. Enabling --opt encrypted on the overlay adds IPsec on top, and the docs are explicit that encryption has a non-negligible performance penalty — budget for a lower effective MTU and test before production.
The same arithmetic explains the usual suspects:
| Path | Typical effective MTU |
|---|---|
| Plain Ethernet | 1500 |
| PPPoE | 1492 |
| IPsec/GRE site-to-site VPN | 1400–1450 |
| WireGuard, cloud VPN clients, VXLAN overlays | 1400–1420 |
| Some cloud underlays and jumbo-free VPCs | 1400–1450 |
If your containers work on the office LAN and fail from home, the difference is almost always the tunnel the laptop is sitting in.
The fixes, in order of preference
1. Match the network to the path. Create bridge networks with the MTU your traffic actually needs — per network, no restart:
docker network create -o com.docker.network.driver.mtu=1420 vpn-net
For the default bridge and for new networks in general, use the daemon options shown in the table above.
2. Clamp MSS on the router instead. If you control the path, TCPMSS clamping makes the senders agree on a workable segment size rather than papering over it per network. On a Linux router:
sudo iptables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN \
-j TCPMSS --clamp-mss-to-pmtu
That is router-side policy — Docker documents no equivalent flag — but it fixes every container at once, including ones you had forgotten about.
3. Fix the underlay. On overlay networks, verify the host interface MTU first (ip -br link show). If the underlay can be raised to 1500, everything above it recalculates; if it cannot, the overlay stays at underlay minus encapsulation.
What does not work: lowering the MTU on one container, hoping the application retries, or turning off PMTUD. Applications like TLS and SSH have no lever here — the network either delivers full-size packets or it does not.
Docker Desktop notes
On Desktop the engine runs inside a VM and outbound container traffic is NAT’d inside that VM and handed to the host over a shared-memory channel rather than a real virtual NIC, so host-side MTU mismatches rarely reproduce the way they do on a Linux server. Two practical consequences: a black hole seen on a Linux host usually will not appear on your laptop (do not use Desktop to reproduce it), and host ping to a container does not work at all there. Do MTU work on the environment where the failure happens, from inside the container.
The bottom line
MTU bugs have a fingerprint — small packets fine, large packets silently dropped — and you confirm them with ping -M do or tracepath, not packet captures. Docker exposes MTU at exactly three levels (daemon --mtu, per-network com.docker.network.driver.mtu, and swarm’s --network-control-plane-mtu), nothing called --mtu exists on docker network create, and changing daemon config never repairs an existing network. Set the network to match the path, or clamp MSS on the router; then that mysterious TLS hang becomes a five-minute fix.