How to fix unable to configure the Docker daemon with file /etc/docker/daemon.json in Docker

DockerINTERMEDIATEHIGHUpdated Jan 10, 2026· 665 views

This error occurs when Docker cannot parse or apply settings from daemon.json due to JSON syntax errors, conflicting configuration options, permission issues, or invalid values. The fix depends on whether the conflict is between flags and config file settings, or a simple syntax issue.

Quick fix

Fixes unable to configure the Docker daemon with file /etc/docker/daemon.json

sudo journalctl -u docker.service -n 50 --no-pager

Check Docker daemon logs for specific error
Validate JSON syntax
Fix empty file error (EOF)
Resolve hosts configuration conflict

docker — error

$sudo journalctl -u docker.service -n 50 --no-pager
unable to configure the Docker daemon with file /etc/docker/daemon.json

What this error means

When Docker starts, the daemon reads its configuration from `/etc/docker/daemon.json` (on Linux) or the equivalent location on Windows/macOS. This JSON file allows you to configure logging drivers, storage options, network settings, and many other daemon behaviors without modifying service files. The "unable to configure the Docker daemon with file" error indicates that Docker found and attempted to read the daemon.json file, but encountered a problem that prevents successful configuration. This could be: - **JSON syntax errors**: Invalid JSON formatting, missing commas, unclosed brackets, or trailing commas - **Configuration conflicts**: The same option is specified both in daemon.json AND as a command-line flag (most commonly the `hosts` option) - **Invalid values**: Using wrong data types (e.g., `"false"` as a string instead of `false` as a boolean) - **Permission issues**: The daemon cannot read the file due to filesystem permissions - **Reserved runtime names**: Using reserved names like "runc" in the runtimes configuration This is a critical error because Docker will refuse to start until the configuration issue is resolved, leaving you unable to run any containers.

Typical symptoms

Docker daemon fails to start with 'unable to configure the Docker daemon with file /etc/docker/daemon.json'
Error message mentions 'the following directives are specified both as a flag and in the configuration file'
Docker service shows as 'failed' in systemctl status
'docker ps' and other commands fail with 'Cannot connect to the Docker daemon'
Error occurs immediately after editing daemon.json
journalctl shows JSON parsing errors or configuration validation failures
Docker Desktop fails to start on Windows/macOS after changing settings

Common causes

JSON syntax error in daemon.json (missing commas, unclosed brackets, trailing commas)
Conflicting 'hosts' option specified in both daemon.json and systemd service file
Empty daemon.json file (must contain at least '{}' if present)
Wrong data type for configuration values (e.g., string 'false' instead of boolean false)
Permission denied - cannot read /etc/docker/daemon.json
Using reserved runtime name 'runc' in custom runtime configuration
UTF-16 encoding or BOM characters in the file
Conflicting 'group' option on Windows between Docker Desktop settings and daemon.json
Invalid or unrecognized configuration keys
File copied from web contains invisible/special characters

How to fix "unable to configure the Docker daemon with file /etc/docker/daemon.json"

1Check Docker daemon logs for specific error

First, get the exact error message to understand what's wrong:

On Linux (systemd):

bash

sudo journalctl -u docker.service -n 50 --no-pager

Or check the service status:

bash

sudo systemctl status docker.service

On Windows (Docker Desktop):

Check the Docker Desktop troubleshooting logs or Event Viewer.

Common error patterns to look for:

- EOF - Empty or truncated file
- json: cannot unmarshal - Wrong data type
- directives are specified both as a flag and in the configuration file: hosts - Configuration conflict
- configuration validation from file failed - Invalid configuration value
- permission denied - File access issue

2Validate JSON syntax

The most common cause is invalid JSON. Validate your daemon.json file:

Using jq (recommended):

bash

sudo cat /etc/docker/daemon.json | jq .

If valid, it will pretty-print the JSON. If invalid, it will show the error location.

Using Python:

bash

python3 -c "import json; json.load(open('/etc/docker/daemon.json'))"

Using an online validator:

Copy the contents and paste into https://jsonlint.com/

Common JSON mistakes:

json

// WRONG - trailing comma
{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
}

// CORRECT - no trailing comma
{
  "storage-driver": "overlay2",
  "log-driver": "json-file"
}

json

// WRONG - missing comma between entries
{
  "storage-driver": "overlay2"
  "log-driver": "json-file"
}

// CORRECT - comma between entries
{
  "storage-driver": "overlay2",
  "log-driver": "json-file"
}

3Fix empty file error (EOF)

If the error mentions EOF or the file is empty/blank, the file must contain at least an empty JSON object:

Check if file is empty:

bash

sudo cat /etc/docker/daemon.json

If empty or doesn't exist, create it with valid content:

bash

echo '{}' | sudo tee /etc/docker/daemon.json

Or add some basic configuration:

bash

cat << 'EOF' | sudo tee /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

Then restart Docker:

bash

sudo systemctl restart docker

4Resolve hosts configuration conflict

This is the most common conflict. On Debian/Ubuntu systems with systemd, Docker is started with a -H flag by default. If you also specify hosts in daemon.json, Docker fails.

Error message:

bash

the following directives are specified both as a flag and in the configuration file: hosts

Solution 1: Create a systemd override file

bash

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo cat << 'EOF' > /etc/systemd/system/docker.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd
EOF

This clears the default -H flag, allowing daemon.json to control the hosts setting.

Reload and restart:

bash

sudo systemctl daemon-reload
sudo systemctl restart docker

Solution 2: Use systemctl edit (interactive)

bash

sudo systemctl edit docker.service

Add the same content as above, save, and restart.

Solution 3: Remove hosts from daemon.json

If you don't need remote access, simply remove the hosts key from daemon.json and use the default Unix socket.

5Fix wrong data types in configuration

JSON requires specific data types. Boolean values must not be quoted.

WRONG - strings instead of booleans:

json

{
  "iptables": "false",
  "live-restore": "true"
}

CORRECT - actual booleans:

json

{
  "iptables": false,
  "live-restore": true
}

WRONG - numbers as strings:

json

{
  "max-concurrent-downloads": "3"
}

CORRECT - actual numbers:

json

{
  "max-concurrent-downloads": 3
}

Refer to the Docker documentation for the correct type of each configuration option.

6Fix permission issues

The Docker daemon runs as root and needs read access to daemon.json.

Check file permissions:

bash

ls -la /etc/docker/daemon.json

Should show something like:

bash

-rw-r--r-- 1 root root 123 Jan 1 12:00 /etc/docker/daemon.json

Fix permissions if needed:

bash

sudo chown root:root /etc/docker/daemon.json
sudo chmod 644 /etc/docker/daemon.json

For Docker installed via snap:

The config file location is different:

bash

/var/snap/docker/current/config/daemon.json

Check AppArmor isn't blocking access:

bash

sudo dmesg | grep -i apparmor

7Fix reserved runtime name error

If you're configuring custom runtimes and see an error about reserved names:

Error:

bash

runtime name 'runc' is reserved

WRONG:

json

{
  "runtimes": {
    "runc": {
      "path": "/usr/bin/runc"
    }
  }
}

CORRECT - use a different name:

json

{
  "runtimes": {
    "custom-runc": {
      "path": "/usr/local/bin/runc"
    }
  }
}

The names "runc" and "io.containerd.runc.v2" are reserved by Docker.

8Check for encoding issues

Hidden characters or wrong encoding can cause parsing failures.

Check file encoding:

bash

file /etc/docker/daemon.json

Should show: ASCII text or UTF-8 Unicode text

If it shows UTF-16 or mentions BOM, convert it:

bash

sudo iconv -f UTF-16 -t UTF-8 /etc/docker/daemon.json > /tmp/daemon.json
sudo mv /tmp/daemon.json /etc/docker/daemon.json

Check for hidden characters:

bash

cat -A /etc/docker/daemon.json

Look for unusual characters like ^M (carriage return) or non-printable characters.

Recreate the file from scratch:

If in doubt, delete and recreate:

bash

sudo rm /etc/docker/daemon.json
sudo cat << 'EOF' > /etc/docker/daemon.json
{
  "log-driver": "json-file"
}
EOF

9Verify the fix and restart Docker

After making changes, validate and restart:

Validate JSON one more time:

bash

sudo cat /etc/docker/daemon.json | jq .

Restart Docker:

bash

sudo systemctl daemon-reload  # If you modified systemd files
sudo systemctl restart docker

Verify Docker is running:

bash

sudo systemctl status docker
docker ps
docker info

Check that your configuration is applied:

bash

docker info | grep -i "logging driver"
docker info | grep -i "storage driver"

The output should reflect the settings in your daemon.json.

Advanced notes

### Understanding Docker Daemon Configuration Priority

Docker daemon configuration can come from multiple sources. Here's the priority order (highest to lowest):

1. Command-line flags (e.g., dockerd --storage-driver overlay2)
2. Environment variables (some options)
3. daemon.json configuration file

When the same option is specified in multiple places, Docker will either:
- Use the highest priority source (for most options)
- Fail with a conflict error (for the hosts option specifically)

### Common daemon.json Options

json

{
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "live-restore": true,
  "default-address-pools": [
    {"base": "172.17.0.0/16", "size": 24}
  ],
  "dns": ["8.8.8.8", "8.8.4.4"],
  "max-concurrent-downloads": 3,
  "max-concurrent-uploads": 5,
  "debug": false,
  "tls": true,
  "tlscacert": "/etc/docker/ca.pem",
  "tlscert": "/etc/docker/server-cert.pem",
  "tlskey": "/etc/docker/server-key.pem"
}

### Windows-Specific Issues

On Windows, daemon.json is typically located at:
- Docker Desktop: %USERPROFILE%\.docker\daemon.json or via Docker Desktop settings UI
- Docker Engine: C:\ProgramData\Docker\config\daemon.json

The group option conflict is common on Windows when Docker Desktop sets a default group that conflicts with daemon.json settings.

### macOS-Specific Issues

On macOS with Docker Desktop, configuration is managed through the Docker Desktop UI. The daemon.json file is at:

bash

~/.docker/daemon.json

Be careful editing this file directly as Docker Desktop may override your changes.

### Proxy Configuration (Docker Engine 23.0+)

In Docker Engine 23.0 and later, you can configure proxy settings in daemon.json:

json

{
  "proxies": {
    "http-proxy": "http://proxy.example.com:3128",
    "https-proxy": "http://proxy.example.com:3128",
    "no-proxy": "localhost,127.0.0.1,.example.com"
  }
}

Note: Earlier versions required configuring proxies via systemd environment files.

### Backup and Recovery

Always backup your daemon.json before making changes:

bash

sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.backup

If Docker won't start, you can temporarily move the file:

bash

sudo mv /etc/docker/daemon.json /etc/docker/daemon.json.broken
sudo systemctl restart docker
# Docker should start with defaults
# Then fix daemon.json.broken and restore

### Validating Configuration Before Applying

You can test configuration without restarting Docker by using:

bash

dockerd --validate --config-file /etc/docker/daemon.json

This validates the configuration file without starting the daemon.

Frequently asked questions

What does "unable to configure the Docker daemon with file /etc/docker/daemon.jso" mean?: json (on Linux) or the equivalent location on Windows/macOS. This JSON file allows you to configure logging drivers, storage options, network settings, and many other daemon behaviors without modifying service files. json file, but encountered a problem that prevents successful configuration.
How do I fix "unable to configure the Docker daemon with file /etc/docker/daemon.jso"?: This error occurs when Docker cannot parse or apply settings from daemon.json due to JSON syntax errors, conflicting configuration options, permission issues, or invalid values. The fix depends on whether the conflict is between flags and config file settings, or a simple syntax issue.
What causes "unable to configure the Docker daemon with file /etc/docker/daemon.jso"?: JSON syntax error in daemon.json (missing commas, unclosed brackets, trailing commas) Conflicting 'hosts' option specified in both daemon.json and systemd service file Empty daemon.json file (must contain at least '{}' if present)
Is the "unable to configure the Docker daemon with file /etc/docker/daemon.jso" error serious?: Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading

📚Docker Official Documentation
📖
Daemon - Official Docker Documentation(Official Docs)
📖
Troubleshooting the Docker daemon - Docker Docs(Official Docs)
📖
dockerd CLI Reference - Docker Docs(Official Docs)
💬
unable to configure the Docker daemon with file /etc/docker/daemon.json: EOF - Stack Overflow(Stack Overflow)
💬
Unable to start docker after configuring hosts in daemon.json - Stack Overflow(Stack Overflow)
💬
Where's docker's daemon.json? (missing) - Stack Overflow(Stack Overflow)
💬
Unable to start the Docker daemon if file daemon.json exist - Stack Overflow(Stack Overflow)
🐙
fatal: unable to configure the Docker daemon - group directive conflict - GitHub(GitHub)
🐙
Cannot set hosts in daemon configuration - GitHub(GitHub)
🐙
Update daemon.json, start failed - GitHub(GitHub)
🔗
100 Common Docker Errors & Solutions - Dev.to

How to fix unable to configure the Docker daemon with file /etc/docker/daemon.json in Docker

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "unable to configure the Docker daemon with file /etc/docker/daemon.json"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading