Break/Fix 10: MTU mismatch causes intermittent network failures

Reported symptoms

●Connections to/from the container succeed for small payloads and fail for large ones.
●`ping -s 1500 CONTAINER_IP` fails; `ping -s 1400 CONTAINER_IP` works.
●HTTPS requests to some endpoints hang or reset; small ones succeed.

Evidence

· `ip link show docker0` — MTU is the default 1500.
· Underlay (VPN, overlay, tunnel) requires a lower MTU (e.g. 1450 for VXLAN).
· `tcpdump` shows large packets being dropped or fragmented oddly.

Diagnosis and resolutionclick to reveal

Root cause

The bridge’s MTU is 1500, but the underlying network requires smaller packets. The kernel does not fragment ICMP-friendly probes in a way that surfaces the issue to normal applications.

Remediation

Set the MTU on the bridge / network to match the underlay: `docker network create --opt com.docker.network.driver.mtu=1450 mynet`. For an existing network: `docker network disconnect && docker network connect` after recreating, or modify the bridge directly.

Verification

`ping -s 1400 CONTAINER_IP` succeeds. Large HTTPS requests complete. Throughput over the network is stable.

Prevention

Document the underlay MTU. Set `com.docker.network.driver.mtu` on every user-defined network. Add a CI / staging check that exercises large payloads.

Diagnosis

docker network inspect mynet | jq '.[].Options'
# {}  ← no MTU set

ip link show docker0 | grep mtu
# 1500

If the underlay is a VPN or overlay with a lower MTU, packets above that size will silently fail or fragment in unexpected ways.

Fix

docker network create \
  --opt com.docker.network.driver.mtu=1450 \
  --opt com.docker.network.bridge.name=br-mynet \
  mynet

For an existing network, recreate the bridge:

docker network rm mynet
docker network create --opt com.docker.network.driver.mtu=1450 mynet
# Containers on the old network need to be reattached.