Fix Docker "client is newer than server" version error

What this error means

Error: "Error response from daemon: client is newer than server (or server API too old)"

The Docker CLI and Docker Engine (daemon) talk via a versioned HTTP API. This error occurs when the CLI attempts to use a higher API version than the daemon supports. Fix by aligning versions (preferred) or by instructing the CLI to use an older API version.

Quickstart (TL;DR)

• Check versions: docker version or query /version on the daemon.
• Preferred: upgrade the daemon to match or exceed the CLI version.
• Alternative: install a matching older CLI.
• Temporary workaround: set DOCKER_API_VERSION to the server’s ApiVersion.
• Pin versions to avoid future drifts.

Minimal working example

Use this to quickly recover access and verify the fix.

# 1) Get the server’s API range via the socket (works even when CLI fails)
sudo curl --silent --unix-socket /var/run/docker.sock http://localhost/version
# Example output snippet:
# {"Version":"20.10.23","ApiVersion":"1.41","MinAPIVersion":"1.12", ...}

# 2) Temporarily force the CLI to use the server’s ApiVersion (example: 1.41)
export DOCKER_API_VERSION=1.41

# 3) Test a basic command
docker ps

# 4) Confirm both sides now talk
docker version

Unset later with unset DOCKER_API_VERSION.

Step-by-step fixes

1) Detect the mismatch

• Try docker version. If it errors, use the socket directly:

sudo curl --unix-socket /var/run/docker.sock http://localhost/version | sed 's/,/\n/g'
# Look for ApiVersion and MinAPIVersion

• Remote daemon over TCP/TLS:

# Replace host/port as appropriate
curl --silent https://remote-host:2376/version --cacert ca.pem --cert cert.pem --key key.pem

Record:

• Server ApiVersion (max) and MinAPIVersion.
• CLI’s supported range (shown by docker version under Client > API version).

2) Preferred fix: upgrade the daemon

Upgrade the Docker Engine so its ApiVersion >= the client’s.

• Docker Desktop (Windows/macOS): update via the UI or:

# macOS (Desktop via Homebrew Cask)
brew upgrade --cask docker

• Linux (example: Ubuntu/Debian using Docker’s repo):

# Ensure you use the official Docker repository first
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
sudo systemctl restart docker

• Linux (RHEL/CentOS/Fedora using Docker’s repo):

sudo dnf makecache
sudo dnf install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker

Remote host: upgrade on that host (via SSH), since the CLI version on your laptop won’t change the server.

Verify:

docker version

3) Alternative: align by downgrading the CLI

When you cannot upgrade the server, install a CLI compatible with the server’s ApiVersion.

• macOS (Homebrew):

# Show available versions if you use a versioned tap or formula pinning
brew info docker
# Install/rollback as your tap supports
brew reinstall docker

• Ubuntu/Debian (pin a specific CLI):

# List available versions
apt-cache madison docker-ce-cli
# Install a specific version (replace with an available version string)
sudo apt-get install -y docker-ce-cli=<VERSION>

• Use a static CLI binary (quick test, no system-wide change):

# Place a compatible docker client binary in a temp dir and prefer it
chmod +x ./docker
PATH="$PWD:$PATH" ./docker version

4) Temporary workaround: set DOCKER_API_VERSION

Use this to get unblocked quickly; plan a real fix afterward.

# Choose a value within [server.MinAPIVersion, server.ApiVersion]
export DOCKER_API_VERSION=1.41
# Works for docker and docker compose v2

Note: Some features may still fail if the server is too old.

5) Target the right daemon with contexts

If you have multiple daemons, ensure the CLI is talking to the intended one.

docker context ls
docker context use default    # or a specific remote
# Or override per-command
docker --context my-remote ps

6) Prevent future drifts (pinning)

• Pin engine and CLI package versions in your base images and servers.
• In CI, install explicit versions and verify with docker version.
• Document a supported version range for developers.

Fix options at a glance

Pitfalls and gotchas

• Forgetting to unset DOCKER_API_VERSION when switching hosts can cause new errors. Use per-shell exports or wrapper scripts.
• Docker Compose v2 uses the Docker CLI. If the CLI is blocked, Compose is blocked too. The env var applies to Compose v2 as well.
• Very old daemons may lack features (BuildKit, manifest lists, cgroup v2). Even with a forced API version, build/run may fail.
• Mixing vendor packages (OS distro’s Moby vs Docker CE) can complicate upgrades. Standardize your source and document it.
• Remote contexts: your local upgrade doesn’t change a remote server. Always check docker context ls and docker version (Server section).

Performance and compatibility notes

• Forcing an older API version does not materially change performance; it only hides newer endpoints. However, some optimizations (e.g., advanced BuildKit features) may be unavailable, making builds slower.
• Remote TLS connections add latency; upgrading the daemon to natively support your client avoids retries and capability negotiation overhead.
• Keeping engine and CLI within the same release family reduces subtle incompatibilities in logs, events, and build features.

FAQ

• Q: Does Docker auto-negotiate API versions?

  • A: The client selects a version to use. If it’s higher than the server supports, you’ll see this error. Setting DOCKER_API_VERSION forces a lower version.

• Q: Which value should I set for DOCKER_API_VERSION?

  • A: Use the server’s ApiVersion from /version. Ensure it’s not lower than MinAPIVersion and is supported by your client.

• Q: Will this affect Kubernetes on the node?

  • A: If Kubernetes uses the same Docker daemon, upgrading the daemon affects it. Coordinate changes with your cluster management.

• Q: Is upgrading the client enough?

  • A: Upgrading the client alone helps only if the server is already new enough. The error specifically occurs when the client is newer than the server.