Why UDP Fails in Docker Bridge Networks and How to Fix It

In recent work I encountered a puzzling UDP connectivity issue in Docker; I found a good article, shared it here, and kept a record for future reference.

Problem Background

While working with a Docker container, a UDP‑based application could not communicate, whereas the same service worked fine over TCP. The UDP server was bound to 0.0.0.0 on the host (or a container with --network=host) and a client running in a bridge‑network container could not reach it.

Tests showed that the issue does not appear when:

Using TCP.

Binding the UDP server to a specific interface IP instead of 0.0.0.0.

Other UDP services such as dnsmasq work correctly.

There are existing Docker issues ( moby#15127 , iri#961 ) but no solid solution.

Reproducing the Issue

On Ubuntu 16.04 I used nc to listen on port 56789 on the host, then started a container in bridge mode and sent data with nc. The first packet was received, but subsequent packets were lost.

$ nc -ul 56789
$ ss -uan | grep 56789

Running the client inside the container:

$ docker run -it alpine sh
# nc -u 172.16.13.13 56789

The container’s IP was 172.17.0.3, connected to the virtual bridge docker0 (172.17.0.1); the host’s external interface was 172.16.13.13.

tcpdump Capture Analysis

Capturing on docker0 revealed that the first client‑to‑server packet was sent, but the server’s reply triggered an ICMP “port unreachable” message, after which communication stopped.

11:20:43.973286 IP 172.17.0.3.38908 > 172.16.13.13.56789: UDP, length 6
11:20:50.102018 IP 172.17.0.1.56789 > 172.17.0.3.38908: UDP, length 6
11:20:50.102129 IP 172.17.0.3 > 172.17.0.1: ICMP 172.17.0.3 udp port 38908 unreachable, length 42

Root Cause Analysis

The server’s reply packets carried the source address of docker0 instead of the expected eth0 address, causing the client to treat them as illegal and generate ICMP errors.

Two key observations:

UDP’s source‑address selection differs from TCP’s because UDP is stateless; the kernel chooses the outgoing interface IP for each packet.

Applications that use recvmsg / sendmsg with the IP_PKTINFO socket option can control the source address, while those using plain recvfrom / sendto rely on the kernel’s routing decision.

Strace of a working dnsmasq instance shows setsockopt(..., IP_PKTINFO, 1) and the use of recvmsg / sendmsg. The problematic application uses IPv6 sockets, recvfrom / sendto, and does not set IP_PKTINFO, leading to the wrong source address.

socket(PF_INET, SOCK_DGRAM, IPPROTO_IP) = 4
setsockopt(4, SOL_SOCKET, SO_REUSEADDR, [1], 4) = 0
bind(4, {AF_INET, sin_port=htons(54), sin_addr=inet_addr("0.0.0.0")}, 16) = 0
setsockopt(4, SOL_IP, IP_PKTINFO, [1], 4) = 0

In contrast, the failing app’s trace lacks the IP_PKTINFO call and uses IPv6 sockets with recvfrom / sendto.

Solution

Switch to TCP if possible – communication works without the issue.

Bind the UDP server to a specific host interface IP instead of 0.0.0.0, e.g. nc -ul 172.16.13.13 56789. Packets addressed to other IPs are dropped, preventing the wrong source address.

Modify the application to set IP_PKTINFO on the socket and use recvmsg / sendmsg for data transfer, ensuring the kernel uses the intended source address.

References

Docker UDP issue analysis – cizixs.com

Setting the source IP for a UDP socket – StackOverflow

Linux: obtaining routing destination IP from UDP packet – cnblogs.com

Source IP address selection – IBM documentation

UDP recvmsg returning destination address – blog.chinaunix.net

Unknown UDP quirks – cloud.tencent.com