Fix Docker daemon not starting

When systemctl start docker fails, every container on the server is down, and the message on screen rarely says why. The real cause is almost always in the daemon's log. This guide shows how to read it and fixes the errors seen most often on a VPS, from a typo in daemon.json to a full disk.

Before you start

• SSH access to the VPS with a sudo user. If SSH is not working either, use the browser console from your VPS provider's control panel.
• Docker Engine installed from Docker's repository or your distribution's packages.
• A note of anything you changed recently: an edit to /etc/docker/daemon.json, an upgrade, a new disk or a firewall change.

Read the actual error

Start with the service status:

sudo systemctl status docker --no-pager

Then read the daemon's recent log, which holds the real message:

sudo journalctl -u docker -n 50 --no-pager

Look for lines containing failed to start daemon, unable to configure, or error. The text after the colon is the cause. Also check containerd, which Docker depends on:

sudo systemctl status containerd --no-pager

If you see start request repeated too quickly, systemd has given up after several fast failures. Fix the cause, then clear the counter:

sudo systemctl reset-failed docker

For more ways to filter logs, see the journalctl guide.

Invalid daemon.json

The most common cause. A missing comma, a trailing comma or a smart quote makes the whole file invalid. Check it:

sudo dockerd --validate --config-file /etc/docker/daemon.json

A valid file prints configuration OK. Otherwise you get the line with the problem. You can also check pure JSON syntax with:

sudo python3 -m json.tool /etc/docker/daemon.json

Fix the file and start Docker again. If you are unsure, move it aside to test with defaults:

sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo systemctl start docker

Option set in two places

An error like this means the same setting is in daemon.json and on the command line in the systemd unit:

the following directives are specified both as a flag and in the configuration file: hosts

Usually it is hosts. Ubuntu's unit starts dockerd with -H fd://. Either remove hosts from daemon.json, or override the unit's start command:

sudo systemctl edit docker

Add these lines in the editor, save and close:

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd

The empty ExecStart= clears the original. Then reload and start:

sudo systemctl daemon-reload
sudo systemctl start docker

Storage driver and overlay errors

Messages like error initializing graphdriver or overlay2 is not supported point to the storage layer:

• The kernel module is missing after a kernel update without a reboot. Reboot the VPS, then check with lsmod | grep overlay.
• daemon.json forces a driver that does not suit the filesystem. Remove any storage-driver entry and let Docker pick the default.
• The data-root is on an XFS filesystem without ftype=1. Check with xfs_info /var/lib/docker | grep ftype. The fix is a filesystem created with ftype=1.
• The data-root path does not exist because a disk is not mounted. Check docker's data path in daemon.json and run findmnt.

Disk full

Docker cannot start when it cannot write its state:

df -h / /var/lib/docker
df -i /

The second command checks inodes, which can run out even when there is free space. Free space by clearing old logs or files outside Docker first, since Docker commands need the daemon running. Large container logs under /var/lib/docker/containers can be emptied with sudo truncate -s 0 FILE. Free up disk space on a Linux VPS covers the rest.

iptables and firewall conflicts

Errors such as failed to create NAT chain DOCKER or iptables: No chain/target/match mean Docker cannot set up its network rules:

• A firewall service flushed Docker's rules. Restart the firewall first, then Docker: sudo systemctl restart firewalld docker or reload UFW and then restart Docker.
• The kernel was updated and the matching netfilter modules are not loaded yet. Reboot.
• The iptables command points to a backend that does not work on your system. On Debian and Ubuntu, check with sudo update-alternatives --display iptables.

As a last resort for diagnosis only, Docker can start without managing iptables ("iptables": false in daemon.json), but published ports and container internet access will then not work.

Check it works

sudo systemctl start docker
sudo systemctl is-active docker
docker run --rm hello-world

is-active should print active, and the test container should print its greeting. Then confirm your stacks came back with docker ps.

Troubleshooting

• Docker starts, then stops a minute later: a container or plugin crashes the daemon, or containerd stops. Read journalctl -u docker -u containerd -f while it happens.
• Cannot connect to the Docker daemon but the service is active: your user is not in the docker group, or DOCKER_HOST points elsewhere. See Fix "permission denied" on the Docker socket.
• Error mentions docker.sock: address already in use: an old socket file or a second daemon. Stop both docker.socket and docker.service, remove /var/run/docker.sock, and start again.
• Nothing in the log at all: the unit may be masked. Run sudo systemctl unmask docker docker.socket.

Next steps

• Prevent full disks: Free disk space with docker system prune.
• If you are still stuck, open a support ticket with the last 50 lines of the Docker log.