Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker will not start after you add a TCP listener or hosts

Errordocker.socket: Failed with result 'service-start-limit-hit'

Short answer

service-start-limit-hit only says systemd gave up after repeated failed starts. The real error is in why dockerd exits. After you enable a TCP listener, it is nearly always the same option set twice: hosts in daemon.json and -H on the systemd command line. Set it in one place only, reload systemd and restart.

  • Applies to Docker Engine 28, Ubuntu 24.04, Debian 12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the daemon in the foreground with the same config. It prints its own error and does not hide it behind systemd's retry limit. Stop with Ctrl+C.

    sudo dockerd
  2. 2Match what you see, then jump to its fix

    1. 1unable to configure the Docker daemon with file /etc/docker/daemon.json: the following directives are specified both as a flag and in the configuration file: hostshosts is set in daemon.json and in the systemd unitFix
    2. 2same message, after following a guide that edits docker.service with systemctl editYou use a systemd override with -H and also kept hosts in daemon.jsonFix
    3. 3the following directives are specified both as a flag and in the configuration file: <option name>Another option is set both as a flag and in daemon.jsonFix

What does the error look like?

  • docker.socket: Failed with result 'service-start-limit-hit'
  • docker.service: Failed with result 'exit-code'
  • the following directives are specified both as a flag and in the configuration file: hosts

Cause 1 of 3

hosts is set in daemon.json and in the systemd unit

1Check

On Debian and Ubuntu the packaged unit starts dockerd with -H fd://. If /etc/docker/daemon.json also has a hosts entry, the daemon refuses to start.

cat /etc/docker/daemon.json
systemctl cat docker.service | grep ExecStart

2Fix

Create a drop-in that empties the unit's ExecStart and starts dockerd without -H. The hosts list in daemon.json then decides where it listens. Keep a unix socket in that list if you still want the local CLI to work.

# /etc/systemd/system/docker.service.d/docker.conf
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd

# /etc/docker/daemon.json
{ "hosts": ["unix:///var/run/docker.sock", "tcp://127.0.0.1:2375"] }

3Verify

Reload systemd and restart Docker, then check the daemon is active.

sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl is-active docker

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

You use a systemd override with -H and also kept hosts in daemon.json

1Check

The remote-access guide sets the listener in a systemd override. If you do that, daemon.json must not also contain hosts. Having both is the conflict, from the other side.

systemctl cat docker.service
grep hosts /etc/docker/daemon.json

2Fix

Pick one method. To keep the override, delete hosts from daemon.json, then reload and restart.

sudo systemctl edit docker.service
# [Service]
# ExecStart=
# ExecStart=/usr/bin/dockerd -H fd:// -H tcp://127.0.0.1:2375

3Verify

Restart and confirm dockerd listens on the port.

sudo systemctl daemon-reload
sudo systemctl restart docker.service
sudo netstat -lntp | grep dockerd

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

Another option is set both as a flag and in daemon.json

1Check

Any option can trigger the same refusal, not only hosts. The message names the option. Look for it in the unit's ExecStart line and in daemon.json.

systemctl cat docker.service | grep ExecStart
cat /etc/docker/daemon.json

2Fix

Keep the option in one place and delete it from the other.

sudoedit /etc/docker/daemon.json

3Verify

Restart the service and check it is active.

sudo systemctl restart docker
sudo systemctl is-active docker

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Choose one way to configure the daemon, daemon.json or systemd flags, and keep to it.
  • After any change run dockerd in the foreground once to see its error before blaming systemd.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

The docker command cannot reach the Docker daemon

Cannot connect to the Docker daemon at unix:///Users/<user>/.docker/run/docker.sock. Is the docker daemon running?

This error means the docker client could not talk to a running daemon.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.