Fixing Docker Swarm Startup Failures on Debian 13 Due to Network Timing

Docker on Debian 13 sometimes fails to start in Swarm mode after a reboot. A common symptom is:

systemctl status docker
× docker.service - Docker Application Container Engine
     Active: failed (Result: exit-code)

Meanwhile, Swarm reports errors like:

failed to start cluster component: could not find local IP address

This happens because Docker tries to bind its Swarm advertise address before the network is fully initialized.

The Problem

On modern Debian systems, services start in parallel. Docker may attempt to start before the network interface has an IP.

Swarm mode requires an IP to advertise to other nodes. If the IP isn’t ready, Docker exits with failure, and the Swarm cluster cannot form.

The Solution: Delay Docker Startup Until Network is Ready

We can solve this with a small systemd service that waits for the network before allowing Docker to start.

1. Create a Delayed Start Unit

Create /etc/systemd/system/docker-delayed.service:

[Unit]
Description=Start Docker after network is online with delay
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/bin/bash -c 'for i in {1..30}; do ip route get 1 >/dev/null 2>&1 && exit 0; sleep 1; done; sleep 5'
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

This unit:

• Waits up to 30 seconds for the network to have a valid IP.
• Adds an extra 5-second buffer.
• Ensures Docker starts only when the network is ready.

2. Make Docker Depend on the Delay

Create an override for Docker:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/override.conf > /dev/null <<'EOF'
[Unit]
After=docker-delayed.service
Requires=docker-delayed.service
EOF

This tells systemd to start Docker only after docker-delayed.service has completed.

3. Reload and Enable Services

sudo systemctl daemon-reload
sudo systemctl enable docker-delayed.service
sudo systemctl restart docker

4. Verify

Check the delayed service:

systemctl status docker-delayed

Check Docker:

systemctl status docker
docker info

If using Swarm:

docker node ls

Swarm should now bind correctly to the host IP without errors.

Conclusion

Docker Swarm startup failures on Debian 13 are usually caused by network timing issues, not Docker itself.

By adding a simple systemd unit to delay Docker until the network is ready, you ensure:

• Docker starts reliably on boot
• Swarm binds to the correct IP
• No manual intervention is needed after reboot

This method is lightweight, robust, and fully integrates with Debian’s systemd.