19.3.3.5 Version Compatibility Debug

When Docker operations fail with errors related to API versions, unsupported features, or daemon connectivity, docker version is the first command to run. The information it provides — client version, server version, API version ranges, platform details, and connectivity status — covers the most common root causes of compatibility problems between Docker components.

Diagnosing Connectivity Problems

If the Docker daemon is not running or the client cannot connect to the socket, the Server section of docker version is replaced with an error message:

Client: Docker Engine - Community
 Version:           25.0.3
 API version:       1.44
 ...

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Linux: Start the daemon with:

sudo systemctl start docker
sudo systemctl status docker

macOS/Windows: Start Docker Desktop through the application. The daemon is managed by the Docker Desktop application process.

If the client output is present but the server is missing, the issue is always a daemon connection problem, not a Docker installation problem.

Diagnosing API Version Mismatches

When a command fails with an error like:

Error response from daemon: client version 1.40 is too old. Minimum supported API version is 1.41, please upgrade your client to a newer version

The client's API version is below the daemon's minimum. Run docker version to confirm:

Client API version:  1.40
Server API version:  1.44 (minimum version 1.41)

The fix is to update the Docker CLI to a version that supports API 1.41 or higher.

The reverse error — client API too new for the server — produces:

Error response from daemon: client version 1.45 is too new. Maximum supported API version is 1.44

In this case, the daemon is older than the client. Update the Docker Engine, or force the client to use a lower API version:

DOCKER_API_VERSION=1.44 docker <command>

Comparing Client and Server Versions

A mismatch between client and server versions is normal and expected (for example, a macOS Docker Desktop update may lag behind a Linux server update). However, very large gaps can cause compatibility issues. Check both:

docker version --format "Client: {{.Client.Version}} | Server: {{.Server.Version}}"

If the client version is significantly newer than the server, features added in the client may not be available in the server's API. If the server is significantly newer, the client may not know about new API features.

Verifying Platform Consistency

Platform mismatches between client and server are expected in Docker Desktop environments (Mac CLI connecting to a Linux VM daemon). However, unexpected platform values can indicate you are connected to the wrong Docker context:

docker version --format "Client: {{.Client.Os}}/{{.Client.Arch}} | Server: {{.Server.Os}}/{{.Server.Arch}}"

If the server platform is not what you expect, check which context is active:

docker context ls

The active context (marked with *) determines which daemon the client connects to. To switch contexts:

docker context use my_remote_server

Identifying Experimental Feature Status

If a command fails because an experimental feature is not enabled:

Error response from daemon: This experimental feature is not enabled

Check whether experimental mode is on:

docker version --format "{{.Server.Experimental}}"

If this returns false, experimental features are disabled in the daemon configuration. Enable them by adding "experimental": true to /etc/docker/daemon.json and restarting the daemon.

Debugging Remote Context Issues

When using a Docker context that points to a remote host and the server section is empty or shows unexpected version information, debugging the context connection:

docker --context my_remote_context version

If this fails, the issue is with the remote connection itself (SSH access, TLS certificates, network connectivity) rather than with Docker compatibility. Verify the connection parameters:

docker context inspect my_remote_context

Version Information in Bug Reports

When reporting Docker issues or seeking support, always include the full output of docker version. It provides the exact state of all components without ambiguity:

docker version > docker_version_info.txt

This captures the complete version block including all subsystem versions (containerd, runc, docker-init), which are often relevant when diagnosing runtime-level issues.

Checking runc and containerd Versions for Security

Security advisories for container runtimes are typically tied to specific runc or containerd version ranges. Verify these against known CVE listings:

docker version --format "runc: {{.Server.Runc.Version}} | containerd: {{.Server.Containerd.Version}}"

If the version falls within a vulnerable range, update Docker Engine, which bundles updated runc and containerd versions. On most Linux distributions, this is done through the system package manager:

sudo apt-get update && sudo apt-get upgrade docker-ce

Summary of Version Fields Used in Debugging