Fix Docker daemon not starting

Docker service failed to start? Read the real error with journalctl, then fix an invalid daemon.json, conflicting options, storage driver and overlay errors, a full disk or iptables problems.

  • Intermediate
  • Linux VPS
  • 5 min read

By RunRacks Team · Published

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 the control panel in your Dashboard.
  • 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:

Terminal
sudo systemctl status docker --no-pager

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

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Text
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:

Terminal
sudo systemctl edit docker

Add these lines in the editor, save and close:

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

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

Terminal
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:

Terminal
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

Terminal
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

Was this guide helpful?

Still stuck?

Ask RunRacks AI for a quick answer, or open a ticket and our team will take a look at your server.

Troubleshooting

Fix Nginx 413 Request Entity Too Large

Nginx returns 413 Request Entity Too Large when an upload is bigger than client_max_body_size. Raise the limit for one site or the whole server, match PHP's limits, and test.

  • Beginner
  • Linux VPS
  • 5 min read

Troubleshooting

Is your ISP or router blocking port 12230? How to tell

Work out whether your internet provider, home router, parental controls or a proxy is blocking RDP port 12230, and collect the details support needs to help.

  • Intermediate
  • Windows VPS · Admin RDP
  • 5 min read