Intro
Docker bridge networking is the default way containers communicate on a single host. It gives each container an isolated network namespace, an IP address on a private subnet, and Network Address Translation (NAT) for outbound traffic. The simplicity of the default bridge network is convenient, but it also leads to common configuration mistakes that can cause connectivity failures, security gaps, and unexpected behavior in multi-container applications.
This article is a practical guide to recognizing and fixing those mistakes. You will see concrete examples of misconfigurations, learn how to validate your bridge setups, and follow safe, reversible change procedures. The focus is on developer and DevOps workflows where you need to inspect, test, and roll back changes quickly without disrupting running services. Each major step includes commands, expected output, and a clear explanation of what to look for.
By the end, you will be able to:
- Identify incorrect bridge network configurations in your Docker environment.
- Apply scoped changes to fix connectivity issues without broad downtime.
- Verify that containers can communicate as intended.
- Roll back to a known working state when tests reveal problems.
Version and Environment Inventory
Before changing any Docker bridge networking configuration, you must know exactly what you are working with. A version inventory and topology map prevents guesswork and makes rollback possible. Start by recording the Docker version, OS details, and current network state.
Check Docker Version and OS
Run the following on the Docker host:
docker version --format '{{.Server.Version}}'
Expected output example:
24.0.7
Also check the kernel and OS release because bridge behavior can vary:
uname -r && cat /etc/os-release | head -n 2
Example output:
5.15.0-91-generic
NAME="Ubuntu"
VERSION="20.04.6 LTS (Focal Fossa)"
Record this information in your change log. It is essential for reproducing issues and rolling back if a Docker update changes the default bridge behavior.
List Existing Networks
Inspect all current Docker networks, especially the built-in bridge, host, and none, plus any custom bridge networks:
docker network ls
Example output:
NETWORK ID NAME DRIVER SCOPE
1a2b3c4d5e6f bridge bridge local
7f8e9d0c1b2a host host local
3c4d5e6f7a8b none null local
9b0a1c2d3e4f myapp bridge local
Pay attention to custom bridge networks. The default bridge network (named bridge) has limitations: no automatic DNS resolution between containers, and it is not recommended for production use. Custom bridge networks provide better isolation and built-in DNS.
Inspect Current Bridge Configuration
For each bridge network that matters, inspect its subnet, gateway, and connected containers:
docker network inspect bridge
The output is verbose. Focus on the IPAM section and the Containers section:
"IPAM": {
"Driver": "default",
"Options": null,
"Config": [
{
"Subnet": "172.17.0.0/16",
"Gateway": "172.17.0.1"
}
]
},
"Containers": {
"abc123...": {
"Name": "web1",
"IPv4Address": "172.17.0.2/16"
}
}
For custom networks, the command is similar:
docker network inspect myapp
Expected output includes a specified subnet, for example 172.18.0.0/16, and a gateway 172.18.0.1.
Create a Baseline Configuration File
Save the current state to a text file. This baseline is your rollback reference:
docker network inspect bridge > bridge_baseline.json
docker network inspect myapp > myapp_baseline.json
Now you have a complete picture: Docker version, OS, networks, and their parameters. This is the prerequisite for safely testing changes.
Safe Configuration Path
Making changes to bridge networking should always follow a scoped, testable path. Avoid modifying the default bridge network directly; instead, create new custom bridge networks for experiments. This isolates the change and allows easy rollback by simply disconnecting containers or removing the test network.
Understand Common Configuration Mistakes
Before fixing, recognize the mistakes. The most frequent bridge networking configuration errors are:
- Using the default bridge for inter-container communication: The default bridge does not provide automatic DNS resolution, so containers must use IP addresses or
--link(deprecated) to talk to each other. This leads to brittle configurations. - IP address conflicts or subnet overlaps: When creating custom networks, specifying a subnet that overlaps with an existing network or with the host's physical network causes routing problems.
- Incorrect gateway or
--ipassignment: Assigning a static IP that is outside the subnet or already in use causes container startup failures. - Misunderstanding published ports and bridge NAT: Publishing a port (
-p 8080:80) works by Docker adding iptables rules. If the container has a custom bridge network and the port is not properly exposed, external access fails. - IPv6 misconfiguration: Enabling IPv6 on a bridge network without proper
--ipv6and subnet specification can break connectivity.
Creating a Safe Custom Bridge Network
A correct custom bridge network with a non-default subnet and gateway:
docker network create \
--driver bridge \
--subnet 192.168.100.0/24 \
--gateway 192.168.100.1 \
my_custom_bridge
Expected output:
<network_id>
Verify the new network with docker network inspect my_custom_bridge and check the IPAM.Config section shows the correct subnet and gateway.
Attaching Containers to the Custom Bridge
Run two containers attached to this network:
docker run -dit --name app1 --network my_custom_bridge alpine sh
docker run -dit --name app2 --network my_custom_bridge alpine sh
Now test DNS-based name resolution between them. Custom bridge networks include an embedded DNS server at 127.0.0.11, so containers can resolve each other by name:
docker exec app1 ping -c 2 app2
Expected output shows successful replies:
PING app2 (192.168.100.3): 56 data bytes
64 bytes from 192.168.100.3: seq=0 ttl=64 time=0.120 ms
64 bytes from 192.168.100.3: seq=1 ttl=64 time=0.080 ms
This is a safe, scoped configuration. If something goes wrong, you can remove the test network without affecting the default bridge.
Common Mistake Example: Overlapping Subnets
Suppose you create a second bridge network with a subnet that overlaps the one above:
docker network create --driver bridge --subnet 192.168.100.0/24 bad_overlap
Docker may not error immediately, but when containers from different networks try to communicate or when routing is examined, conflicts appear. In practice, Linux kernel routes may become ambiguous. The safe rule is to never use overlapping subnets on the same host.
To correct, remove the faulty network:
docker network rm bad_overlap
Common Mistake Example: Static IP Outside Subnet
If you try to assign a static IP that is not in the network's subnet:
docker run -dit --name app3 --network my_custom_bridge --ip 10.0.0.5 alpine sh
Docker returns an error:
docker: Error response from daemon: user specified IP address is supported only when connecting to networks with user configured subnets.
This is a clear mistake. The fix is to assign an IP within the subnet, e.g., --ip 192.168.100.10, ensuring it is not already used.
Publishing Ports on Custom Bridge Networks
A frequent mistake is believing that publishing a port on a container attached to a custom bridge is different from the default bridge. The behavior is the same: Docker adds iptables DNAT rules. Test it:
docker run -dit --name web --network my_custom_bridge -p 8080:80 nginx: alpine
Then from the host:
curl http://localhost:8080
Expected output: the default nginx welcome page HTML.
If this fails, check iptables -t nat -L -n for the DOCKER chain to see if the rule exists. A common reason is that the container's process is not listening on the expected port, or another process on the host is already using port 8080.
Verification and Diagnostics
After making changes, you must verify that the network behaves as expected. This section provides concrete commands and expected outputs for each check.
Verify Container-to-Container Connectivity
Using the custom bridge network created earlier, confirm that containers can ping each other by name and IP:
docker exec app1 ping -c 1 app2
docker exec app1 ping -c 1 192.168.100.3
Both should succeed. If name resolution fails but IP ping works, the embedded DNS is not functioning. This can happen if the container was not attached to the custom network at creation or if there are DNS misconfigurations.
Verify Outbound Internet Access
Test that containers can reach the outside world:
docker exec app1 wget -qO- http://example.com | head -n 1
Expected output is the HTML of example.com. If this fails, investigate the host's IP forwarding and iptables MASQUERADE rules. Check IP forwarding:
sysctl net.ipv4.ip_forward
Expected output:
net.ipv4.ip_forward = 1
If it is 0, enable it temporarily with sysctl -w net.ipv4.ip_forward=1 and permanently in /etc/sysctl.conf.
Verify Published Port Mapping
From the host, use ss or netstat to confirm Docker is listening on the published port:
ss -tlnp | grep 8080
Expected output shows docker-proxy or the container's process listening:
LISTEN 0 4096 0.0.0.0:8080 0.0.0.0:* users:(("docker-proxy",pid=1234, fd=4))
Also verify the iptables DNAT rule:
sudo iptables -t nat -L DOCKER -n -v
Look for a rule that maps tcp dpt:8080 to the container's IP and port 80.
Verify Bridge Interfaces
Check that the bridge interface exists on the host and has the correct IP:
ip addr show br-<short_network_id>
For example, if the network ID is 9b0a1c2d3e4f, the bridge is br-9b0a1c2d3e4f. Its IP should be the gateway 192.168.100.1/24.
Using Docker Network Connect for Dynamic Attachment
A safe way to add connectivity to a running container without recreating it is docker network connect:
docker network connect my_custom_bridge app1
Then verify that the container now has an additional IP:
docker exec app1 ip addr show eth1
Expected output shows an interface with an IP from the custom subnet, e.g., 192.168.100.4/24.
Diagnostic Table for Common Bridge Issues
| Symptom | Likely Cause | Diagnostic Command | Fix |
|---|---|---|---|
| Container cannot reach internet | IP forwarding disabled | sysctl net.ipv4.ip_forward | Enable IP forwarding |
| Containers cannot resolve names on custom network | Not on a user-defined network | docker inspect <container> | grep Networks | Attach to custom network | | Published port not accessible from outside | Firewall blocking or wrong port mapping | ss -tlnp and iptables -t nat -L -n | Fix port mapping or firewall | | Container startup fails with IP error | Static IP outside subnet or duplicate | docker run --ip error | Choose valid IP within subnet | | Overlapping subnets cause routing issues | Multiple networks with same subnet | docker network inspect | Recreate network with unique subnet |
Failure Modes and Recovery
Even with careful planning, things can go wrong. This section covers common failure modes, how to recover, and how to roll back to a known good state.
Failure Mode: Container Loses Network After Change
If you accidentally remove a network that a container is still attached to, Docker will disconnect the container. For example:
docker network rm my_custom_bridge
If app1 was still running, it is now disconnected. To recover, recreate the network and reconnect the container:
docker network create --driver bridge --subnet 192.168.100.0/24 --gateway 192.168.100.1 my_custom_bridge
docker network connect my_custom_bridge app1
Then verify with docker exec app1 ip addr that the interface is back.
Failure Mode: Incorrect Subnet Change
If you realize a new subnet overlaps with the host's LAN, containers may not route correctly. The safest recovery is to stop the affected containers, remove the faulty network, recreate with a correct unique subnet, and reconnect containers.
Step-by-step:
# Disconnect all containers from faulty network
docker network disconnect faulty_net container1
docker network disconnect faulty_net container2
# Remove the faulty network
docker network rm faulty_net
# Create corrected network
docker network create --driver bridge --subnet 10.50.0.0/24 corrected_net
# Reconnect containers
docker network connect corrected_net container1
docker network connect corrected_net container2
Always test connectivity immediately after.
Rollback Using Baseline Configuration
If a change causes unexpected issues, you can restore the original bridge network state. Since the default bridge network cannot be deleted, its configuration is largely static. For custom networks, you can recreate them from your baseline inspection file or note the original parameters.
Example: You changed the subnet of myapp network and now want to revert. If you had recorded its original subnet as 172.18.0.0/16, you can recreate it:
# Disconnect all containers
docker network disconnect myapp containerA
docker network disconnect myapp containerB
# Remove the network
docker network rm myapp
# Recreate with original settings
docker network create --driver bridge --subnet 172.18.0.0/16 --gateway 172.18.0.1 myapp
# Reconnect containers (order may matter for DNS)
docker network connect myapp containerA
docker network connect myapp containerB
This restores the previous subnet. Containers may receive new IP addresses, so applications that rely on static IPs might need updates.
Recovery Checks After Rollback
Always perform a post-rollback verification:
docker network inspect myappshows the original subnet and gateway.- Containers can ping each other by name.
- Published ports still work.
- Outbound internet access works.
Preventing Failure with Config Versioning
Maintain network configuration files in version control. For each network, keep a JSON or YAML file with its intended parameters. Before making changes, commit a rollback script that recreates the original network. This is a key habit for safe operations.
Operations Checklist
This checklist summarizes the safe procedure for modifying Docker bridge networking. Use it every time you need to make changes.
- [ ] Record baseline: Note Docker version, OS, current networks (
docker network ls), and inspect the target network. - [ ] Identify the mistake: Determine whether it is subnet overlap, DNS issue, port mapping, etc.
- [ ] Plan a scoped change: Prefer creating a new custom network rather than altering the default bridge.
- [ ] Apply the configuration change: Use
docker network createwith explicit--subnetand--gatewayif needed. - [ ] Attach test containers: Run lightweight containers (e.g., alpine) to test connectivity.
- [ ] Run verification commands: Check ping by name, ping by IP, outbound internet, and published ports.
- [ ] Inspect iptables and interfaces: Ensure rules and bridge interfaces exist as expected.
- [ ] If failure, rollback: Disconnect containers, remove the new network, recreate original if needed.
- [ ] Document the change and outcome: Update your configuration files and runbook.
- [ ] Monitor for regressions: After rollback, watch logs and connectivity for a reasonable period.
Conclusion
Docker bridge networking is powerful but easy to misconfigure. The most common mistakes involve using the default bridge for inter-container communication, overlapping subnets, incorrect static IP assignments, and misconfigured port publishing. These errors lead to connectivity failures and security risks.
To avoid these problems, always work from a known baseline, make changes in a scoped and reversible way, and verify every change with concrete commands. Create custom bridge networks for applications that need DNS-based service discovery and isolation. When something goes wrong, roll back by recreating the network with the previous settings and reconnecting containers.
By following the safe configuration path and using the operations checklist, you can maintain reliable container networking. The next verified step is to apply this workflow to a non-critical service in your environment, test thoroughly, and gradually extend it to production workloads.