How to fix failed to load daemon config: json: cannot unmarshal in Docker

First, get the full error message to identify which configuration key has the wrong type:

On Linux (systemd):

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

Or check service status:

sudo systemctl status docker.service -l

Look for error patterns like:

- cannot unmarshal string into Go value of type bool - You used "true"/"false" as strings
- cannot unmarshal string into Go value of type int - You quoted a number
- cannot unmarshal object into Go value of type []string - You used an object where an array was expected
- cannot unmarshal array into Go value of type string - You used an array where a single string was expected

The error message will typically include the field name that has the wrong type.

The most common cause is quoting boolean values. Boolean values in JSON must NOT be quoted.

WRONG - strings instead of booleans:

{
  "iptables": "false",
  "debug": "true",
  "live-restore": "true",
  "userland-proxy": "false"
}

CORRECT - actual boolean values:

{
  "iptables": false,
  "debug": true,
  "live-restore": true,
  "userland-proxy": false
}

Common boolean options in daemon.json:
- debug
- tls
- tlsverify
- iptables
- ip-forward
- ip-masq
- ipv6
- userland-proxy
- live-restore
- experimental
- selinux-enabled

Numeric configuration values must also be unquoted.

WRONG - numbers as strings:

{
  "max-concurrent-downloads": "3",
  "max-concurrent-uploads": "5",
  "max-download-attempts": "5",
  "shutdown-timeout": "15"
}

CORRECT - actual numbers:

{
  "max-concurrent-downloads": 3,
  "max-concurrent-uploads": 5,
  "max-download-attempts": 5,
  "shutdown-timeout": 15
}

Common numeric options:
- max-concurrent-downloads
- max-concurrent-uploads
- max-download-attempts
- shutdown-timeout
- default-shm-size (when specified as bytes, not string like "64M")

Proxy configuration requires a specific nested structure. The most common mistake is missing the intermediate default key.

WRONG - proxies directly under config:

{
  "proxies": {
    "httpProxy": "http://proxy.example.com:3128",
    "httpsProxy": "http://proxy.example.com:3128",
    "noProxy": "localhost,127.0.0.1"
  }
}

CORRECT - proxies nested under default (Docker 23.0+):

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:3128",
      "httpsProxy": "http://proxy.example.com:3128",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

CORRECT - new format (Docker Engine 23.0+):

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

Check your Docker version to determine which format to use:

docker --version

Options inside log-opts and storage-opts should generally be strings, but some common mistakes occur:

CORRECT log-opts format (values are strings):

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3",
    "labels": "production_status",
    "env": "os,customer"
  }
}

WRONG - max-file as number:

{
  "log-opts": {
    "max-size": "10m",
    "max-file": 3
  }
}

For log-opts, values should typically be strings since they're passed to the logging driver as key-value pairs.

Storage options are also strings:

{
  "storage-driver": "overlay2",
  "storage-opts": [
    "overlay2.override_kernel_check=true"
  ]
}

Note that storage-opts is an array of strings, not an object.

Some configuration options expect arrays, others expect objects. Using the wrong structure causes unmarshal errors.

Options that expect ARRAYS:

{
  "dns": ["8.8.8.8", "8.8.4.4"],
  "dns-search": ["example.com"],
  "dns-opts": ["ndots:5"],
  "storage-opts": ["overlay2.override_kernel_check=true"],
  "insecure-registries": ["myregistry.local:5000"],
  "registry-mirrors": ["https://mirror.gcr.io"]
}

Options that expect OBJECTS:

{
  "log-opts": {
    "max-size": "10m"
  },
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime"
    }
  },
  "default-address-pools": [
    {"base": "172.80.0.0/16", "size": 24}
  ]
}

Note that default-address-pools is an array of objects, each with base and size keys.

Before restarting Docker, validate your configuration file:

View the current file:

sudo cat /etc/docker/daemon.json

Validate JSON syntax with jq:

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

If the JSON is valid, jq will pretty-print it. If invalid, it shows the error.

Check the file location for your setup:

- Standard Linux install: /etc/docker/daemon.json
- Docker in snap (Ubuntu): /var/snap/docker/current/config/daemon.json
- Windows: C:\ProgramData\docker\config\daemon.json
- macOS Docker Desktop: ~/.docker/daemon.json

Create a fresh, minimal config if needed:

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

After fixing the configuration, restart Docker and verify it's working:

Restart the Docker daemon:

sudo systemctl restart docker

Check the service status:

sudo systemctl status docker

You should see "active (running)" status.

Verify Docker is working:

docker ps
docker info

Verify your configuration was applied:

docker info | grep -A5 "Logging Driver"
docker info | grep "Storage Driver"

The output should reflect your daemon.json settings.