🐳 Docker Error Guide: 'unknown log opt' for the configured log driver

Exact Error Message

$ docker run --log-driver json-file --log-opt syslog-facility=daemon nginx
docker: Error response from daemon: unknown log opt 'syslog-facility' for json-file log driver.

You will see the same class of error with other driver/option mismatches, for example:

docker: Error response from daemon: unknown log opt 'max-size' for syslog log driver.
docker: Error response from daemon: error creating logging driver "jsonfile": no such log driver.

What It Means

Every Docker logging driver accepts only its own set of --log-opt keys. When you pass an option that the selected --log-driver does not recognize, the daemon rejects the container at creation time with unknown log opt '<opt>' for <driver> log driver. Nothing starts, because logging is configured before the container process launches.

This is a validation error, not a runtime failure. Docker is telling you the combination of driver and option is invalid: the option might be perfectly valid for a different driver. For example, max-size belongs to json-file and local, while syslog-facility belongs to syslog and journald. Mixing them across drivers triggers the error.

Common Causes

• Passing a json-file/local rotation option (max-size, max-file) to a driver that does not rotate, like syslog or none.
• Passing a syslog option (syslog-address, syslog-facility, tag formatting) while the driver is json-file.
• A daemon-wide default driver in /etc/docker/daemon.json conflicting with per-container --log-opt flags.
• A typo in the driver name (jsonfile instead of json-file) producing no such log driver.
• Copying a Compose logging: block between services that use different drivers.
• Using an option that only exists in a newer or older Docker version than the one you are running.

Diagnostic Commands

Check the current default logging driver and its configured options:

docker info --format 'Log Driver: {{.LoggingDriver}}'
cat /etc/docker/daemon.json

Inspect a running or failed container to see the driver and options it was given:

docker inspect --format '{{.HostConfig.LogConfig.Type}} {{json .HostConfig.LogConfig.Config}}' <container>

List which options a driver supports by consulting the daemon version:

docker version --format '{{.Server.Version}}'

Reproduce with a minimal container to isolate the offending option:

docker run --rm --log-driver json-file --log-opt max-size=10m hello-world

Step-by-Step Resolution

1. Identify the driver you actually want. json-file and local are file-based and support size rotation; syslog and journald forward to system logging and support facility/tag options.

2. Match the option to the driver. For file rotation with json-file or local, use max-size and max-file:

docker run -d --log-driver json-file \
  --log-opt max-size=10m --log-opt max-file=3 nginx

3. For syslog forwarding, use syslog-specific options and drop the rotation keys:

docker run -d --log-driver syslog \
  --log-opt syslog-address=udp://10.0.0.5:514 \
  --log-opt syslog-facility=daemon \
  --log-opt tag="{{.Name}}" nginx

4. Fix the driver name if you saw no such log driver. Valid built-in names include json-file, local, syslog, journald, fluentd, gelf, awslogs, splunk, and none:

docker run -d --log-driver json-file nginx   # not "jsonfile"

5. Reconcile daemon defaults with per-container flags. If daemon.json sets a default driver, per-container --log-opt must be valid for whichever driver ultimately applies:

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

Then restart the daemon:

sudo systemctl restart docker

6. In Compose, keep the driver and its options consistent per service:

services:
  web:
    image: nginx
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Prevention

• Pick one logging driver as your standard and set it in daemon.json so per-container overrides are rarely needed.
• Keep a reference of which options belong to which driver; do not copy a logging: block between services without checking the driver. The DevOps AI prompt library has prompts that validate a driver-plus-option pairing before you ship it.
• Always set max-size and max-file on file-based drivers so container logs cannot fill the disk, a separate but common failure.
• Test log configuration with a throwaway hello-world run before rolling it into a real service.
• Pin the option set to your Docker server version; verify with docker version when moving configs between hosts.

Related Errors

• error creating logging driver "<name>": no such log driver — the driver name itself is wrong or unavailable.
• configured logging driver does not support reading — docker logs fails under syslog/gelf/awslogs, which do not support read-back.
• json-file logging driver ... disk full — logs filled the disk because rotation options were never set.
• failed to initialize logging driver: dial tcp ... — a remote driver (fluentd/gelf/splunk) cannot reach its endpoint.

Frequently Asked Questions

Why is max-size invalid for syslog? max-size controls on-disk rotation of local log files, which only file-based drivers (json-file, local) perform. Syslog forwards lines to a remote or system logger and has no local file to rotate.

Where do I find the valid options for a driver? They are documented per driver in the Docker logging driver reference and vary by driver: json-file/local take max-size/max-file, syslog takes syslog-address/syslog-facility/tag, and so on.

Can I use different drivers per container? Yes. The driver and its options are per-container, so long as each container’s --log-opt keys are valid for that container’s --log-driver.

Why does docker logs say the driver does not support reading? Drivers like syslog, gelf, fluentd, and awslogs stream logs elsewhere and cannot serve them back. Use json-file, local, or journald if you need docker logs.

Does a daemon.json default cause this? It can. A default driver set daemon-wide combined with a per-container option for a different driver produces the mismatch. Keep them aligned. For more, see the Docker guides.