Docker "Error: network sandbox join failed" in CI

libnetwork builds a per-container network sandbox (its own netns, interfaces, and routes). When joining that sandbox fails - a stale sandbox left by a crashed container, a namespace setup race, or a momentary kernel/netlink hiccup - the container cannot start. This is usually a transient infrastructure failure rather than a config error.

What this error means

A container start fails with a sandbox join error from libnetwork. A retry, or a daemon restart, usually clears it.

Error response from daemon: failed to create endpoint api on network bridge: failed to join network sandbox: error creating veth pair: operation not supported

Common causes

A stale sandbox from a crashed container

A leftover network sandbox can block a new container from joining until it is cleaned up.

A namespace/netlink setup race

Creating the veth pair and joining the namespace can momentarily fail under load.

How to fix it

Re-run the container start

1. Retry the start - sandbox join failures are usually transient.

docker run --rm --network bridge myorg/api:1.4.2

Clean up stale sandboxes via a daemon restart

1. Restart the daemon to clear leftover sandboxes and namespaces.

sudo systemctl restart docker

How to prevent it

• Avoid leaving crashed containers with stale sandboxes.
• Restart the daemon to clear leftover network namespaces.
• Retry transient sandbox-join failures first.

Related guides