DockerSenior

Docker daemon won't start: option set both as a flag and in daemon.json

If daemon.json and the dockerd start-up flags set the same option, Docker refuses to start. On systemd hosts, the hosts key is the usual culprit.

What you see

  • unable 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: hosts: (from flag: [unix:///var/run/docker.sock], from file: [tcp://127.0.0.1:2376])

What it means

dockerd reads options from daemon.json and from its command line. If the same option appears in both, it stops rather than pick one. On Debian and Ubuntu with systemd, the service file always passes -H, so adding a hosts entry to daemon.json creates exactly this conflict.

How to confirm the cause

  1. 1
    Read why the daemon failed
    sudo journalctl -u docker -b | tail -30

    The error names the option that conflicts.

  2. 2
    See how the service starts dockerd
    systemctl cat docker

    Look at ExecStart= for flags such as -H.

Causes and fixes

  • hosts is set in daemon.json and passed with -H

    HOW TO TELL
    The error names hosts.
    ROOT CAUSE
    The default systemd unit on Debian and Ubuntu always starts dockerd with -H, so any hosts key in daemon.json conflicts with it.
    FIX
    Override the unit so it starts dockerd without -H, then reload systemd and start Docker. Setting hosts in daemon.json is not supported on Docker Desktop for Windows or Mac.
    # /etc/systemd/system/docker.service.d/docker.conf
    [Service]
    ExecStart=
    ExecStart=/usr/bin/dockerd
    
    sudo systemctl daemon-reload
    sudo systemctl start docker
  • Another option is duplicated

    HOW TO TELL
    The error names a different directive.
    ROOT CAUSE
    The same setting is in a start-up script or unit flag and in daemon.json.
    FIX
    Remove it from one of the two places.

How to stop it coming back

  • Keep daemon options in daemon.json only, and keep the unit file default.
  • Validate config changes on a staging host before production.

Keep going

Sources

Docker documentation (docs.docker.com), read 18 Nov 2026 from the official docs repository.

Search

Search cheat sheets and projects