containers.run() returns None for the local logging driver, now the Docker Desktop 4.94 default

Start with docker/models/containers.py and trace how containers.run() reads logs based on the logging driver; check when an unreadable driver raises an error on the streaming path. Then review the docstring and the existing test_run_with_json_file_driver and none integration cases in tests/integration/models_containers_test.py; done means readable local logs are returned, the none case remains handled, and the documented behavior matches.

containers.run() returns None instead of the container's output when the container uses the local logging driver. Docker Desktop 4.94.0 made local the default for new Linux containers, so plain run() calls that previously returned output now silently return None for Docker Desktop users.

Environment

• Docker Desktop 4.94.0 on macOS (arm64), Docker Engine 29.8.2, API version 1.56
• docker-py 7.1.0 and 7.2.0 (both behave the same), Python 3.11
• docker info --format '{{.LoggingDriver}}' prints local, with no log-driver set in daemon.json

The Docker Desktop 4.94.0 release notes say: "Changed the default logging driver for new Linux containers to local to enable automatic log rotation and reduce disk usage".

Reproduction

import docker

client = docker.from_env()
out = client.containers.run("alpine:latest", "echo hello", remove=True)
print(repr(out))

Expected: b'hello\n'

Actual: None

Passing log_config=docker.types.LogConfig(type="json-file") makes the same call return b'hello\n'.

Cause

DockerClient.containers.run() decides whether to read the container's output by comparing the configured driver name against a fixed list (docker/models/containers.py on main):

logging_driver = container.attrs['HostConfig']['LogConfig']['Type']

out = None
if logging_driver == 'json-file' or logging_driver == 'journald':
    out = container.logs(stdout=stdout, stderr=stderr, stream=True, follow=True)
...
if stream or out is None:
    return out
return b''.join(out)

For any other driver out stays None and run() returns None without an error. The list was added in 2017 (commit 62fda980e4, "client.containers.run returns None if none of json-file or journald logging drivers used", fixing #1688). At the time the Engine API documentation said logs could only be read with those two drivers, and run() on e.g. syslog failed with 500 ... configured logging driver does not support reading.

That premise no longer holds:

• The local driver is readable. On the same daemon, running detached and then reading the logs works and returns the output: k = client.containers.run("alpine:latest", "echo hello", detach=True); k.wait(); k.logs() returns b'hello\n' with HostConfig.LogConfig.Type == 'local'. docker logs also works.
• The local driver has been available since at least Engine 18.09 (it is listed in the docker info output in #2866).
• The Engine's dual logging documentation says docker logs can read container logs "regardless of the configured logging driver or plugin", unless cache-disabled is set.

There is still a genuinely unreadable case. With the none driver, container.logs() raises APIError 501, which is what the 2017 change was protecting against.

Impact

Anything that relies on the return value of run() breaks on Docker Desktop 4.94 and later without any change on the caller's side. One example is the DataHub CLI (acryl-datahub, datahub docker quickstart), whose preflight check runs a throwaway alpine container to measure free disk space and calls .decode() on the result, so it now fails immediately with AttributeError: 'NoneType' object has no attribute 'decode'.

Possible fixes

1. Add 'local' to the list. One line, and fixes the current case, but other readable drivers (including remote drivers that dual logging makes readable) would still silently return None.
2. Stop deciding by driver name. Always try to read, and return None only if the Engine answers that the driver does not support reading (the 501 above). This matches current Engine behaviour and cannot go stale when drivers are added. It needs a check of when the error is raised on the streaming path (stream=True, follow=True).

Whichever is chosen, the run() docstring currently documents the old behaviour ("STDOUT and STDERR may be read only if either json-file or journald logging driver used... a None object is returned instead", linking to the v1.30 API docs) and would need updating. The Swarm service logs docstrings (docker/models/services.py, docker/api/service.py) carry a similar note but cover a different endpoint, so I have not assumed they are affected.

For tests, tests/integration/models_containers_test.py already has test_run_with_json_file_driver and a none case that asserts out is None, so a local case beside them would follow the existing pattern. The unit tests only exercise the readable path, because fake_api.py hard-codes "LogConfig": {"Type": "json-file"} in the inspect response, so a parametrized unit test over the driver type would also cover the branch that currently has no unit coverage.

Related

Not duplicates, but adjacent reports of run() and logging-driver behaviour: #2866 (run() hangs with the journald driver), #2367, #1924.

Happy to send a PR for either option.