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
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:
sudo systemctl status docker --no-pagerThen read the daemon's recent log, which holds the real message:
sudo journalctl -u docker -n 50 --no-pagerLook 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-pagerIf 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 dockerFor 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.jsonA 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.jsonFix 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 dockerOption 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: hostsUsually 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 dockerAdd these lines in the editor, save and close:
[Service]
ExecStart=
ExecStart=/usr/bin/dockerdThe empty ExecStart= clears the original. Then reload and start:
sudo systemctl daemon-reload
sudo systemctl start dockerDo not open the Docker API on a TCP port without TLS. Anyone who reaches it gets root on your server.
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-driverentry 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 withftype=1. - The `data-root` path does not exist because a disk is not mounted. Check
docker's data path indaemon.jsonand runfindmnt.
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 dockeror reload UFW and then restart Docker. - The kernel was updated and the matching netfilter modules are not loaded yet. Reboot.
- The
iptablescommand points to a backend that does not work on your system. On Debian and Ubuntu, check withsudo 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-worldis-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 -fwhile it happens. - `Cannot connect to the Docker daemon` but the service is active: your user is not in the
dockergroup, orDOCKER_HOSTpoints 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.socketanddocker.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.
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.
Related guides
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
Troubleshooting
Fix "Your credentials did not work" in Remote Desktop
Fix rejected RDP logins: username format, the right password, stale saved credentials, account lockout and Remote Desktop permissions.
- Beginner
- Windows VPS · Admin RDP
- 3 min read