Ubuntu 26.04 LTS – Docker service fails to start after daemon.json edit – Fix & Prevention

📖 ~1 min read

Table of contents

1. Symptom & Impact
2. Environment & Reproduction
3. Root Cause Analysis
4. Quick Triage
5. Step-by-Step Diagnosis
6. Solution – Primary Fix
7. Solution – Alternative Approaches
8. Verification & Acceptance Criteria
9. Rollback Plan
10. Prevention & Hardening
11. Related Errors & Cross-Refs
12. References & Further Reading

Symptom & Impact

Docker workloads stop because dockerd fails at startup with config parse errors.

Environment & Reproduction

Appears after editing /etc/docker/daemon.json for registry or logging options.

sudo systemctl restart docker
sudo systemctl status docker
docker ps

Root Cause Analysis

Invalid JSON syntax or unsupported daemon keys break dockerd initialization.

Quick Triage

Validate config format and inspect service logs.

sudo cat /etc/docker/daemon.json
sudo journalctl -u docker -n 100
dockerd --validate --config-file /etc/docker/daemon.json

Step-by-Step Diagnosis

Identify first invalid field and compare with daemon-supported settings.

python3 -m json.tool /etc/docker/daemon.json
dockerd --help | head -n 40
sudo systemctl cat docker

Solution – Primary Fix

Correct daemon.json syntax or keys, then restart docker.

sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudoedit /etc/docker/daemon.json
sudo systemctl daemon-reload
sudo systemctl restart docker

Solution – Alternative Approaches

Temporarily move daemon.json and run with defaults to restore service quickly.

sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.disabled
sudo systemctl restart docker

Verification & Acceptance Criteria

Docker daemon is active and containers can run successfully.

sudo systemctl is-active docker
docker info
docker run --rm hello-world

Rollback Plan

Restore backup daemon.json if new changes introduce regressions.

sudo mv /etc/docker/daemon.json.bak /etc/docker/daemon.json
sudo systemctl restart docker

Prevention & Hardening

Validate JSON and test config changes in staging before production rollout.

python3 -m json.tool /etc/docker/daemon.json
sudo systemctl status docker

Related Errors & Cross-Refs

Related to storage driver mismatches, cgroup settings, and proxy misconfiguration.

Related tutorial: View the step-by-step tutorial for Ubuntu 26.04 LTS.

View all Ubuntu 26.04 LTS tutorials on the Tutorials Hub →

Browse all common problems & solutions on the Tutorials Hub.

References & Further Reading

Ubuntu Docker engine docs and daemon configuration reference.