Docker Daemon Fails to Start - "unable to configure ... invalid daemon.json" in CI

By Daniel Zoghalchali·Latchkey

The Docker daemon refused to start because /etc/docker/daemon.json is invalid JSON or sets an option that conflicts with a command-line flag. Until the config parses cleanly, dockerd will not come up and every docker command fails to connect.

What this error means

dockerd exits at startup with unable to configure the Docker daemon with file /etc/docker/daemon.json (a JSON parse error) or the following directives are specified both as a flag and in the configuration file. No docker commands work because the daemon never started.

dockerd output

unable to configure the Docker daemon with file /etc/docker/daemon.json:
invalid character '}' looking for beginning of object key string
# or a flag/config conflict:
unable to configure the Docker daemon ... hosts: (from flag: ..., from file: ...)

Diagnose it: read the container, not the compose file

A container that exits immediately in CI has almost always logged the reason and then been cleaned up. Capture the logs and the exit code before changing configuration.

Terminal

# why did it stop?
docker ps -a --format '{{.Names}}\t{{.Status}}\t{{.Image}}'
docker logs <container> 2>&1 | tail -50
docker inspect <container> --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'

Common causes

Malformed JSON in daemon.json

A trailing comma, missing quote, or stray brace makes daemon.json invalid JSON, so the daemon cannot parse its config and refuses to start.

A directive set both as a flag and in the file

Options like hosts/-H specified both on the dockerd command line and in daemon.json conflict, and the daemon aborts rather than guess.

An unknown or unsupported key

A misspelled or version-unsupported config key causes the daemon to reject the file at startup.

How to fix it

Validate and fix the JSON

Confirm daemon.json is well-formed before restarting the daemon.

Terminal

python3 -c "import json;json.load(open('/etc/docker/daemon.json'))" && echo OK
sudo systemctl restart docker

Resolve flag/config conflicts

Choose one place for each option - either the systemd unit/flags or daemon.json, not both.
Remove duplicated directives (commonly hosts/-H) from one side.
Check journalctl -u docker for the exact key the daemon rejected.

How to prevent it

Lint daemon.json as JSON in CI before applying it.
Keep each daemon option in a single source (flags or the file).
Pin to documented config keys for your Docker version.

Frequently asked questions

What causes Docker daemon fails to start?

There are 3 common causes: malformed json in daemon.json, a directive set both as a flag and in the file, and an unknown or unsupported key. A trailing comma, missing quote, or stray brace makes daemon.json invalid JSON, so the daemon cannot parse its config and refuses to start.

How do I fix Docker daemon fails to start?

There are 2 fixes depending on which cause you have: validate and fix the json and resolve flag/config conflicts. Work through them in order, since the first is the most common.

What does Docker daemon fails to start actually mean?

dockerd exits at startup with unable to configure the Docker daemon with file /etc/docker/daemon.json (a JSON parse error) or the following directives are specified both as a flag and in the configuration file.

How do I stop Docker daemon fails to start happening again?

Lint daemon.json as JSON in CI before applying it. The prevention section lists 3 changes that keep it from recurring.