🚨 Docker Error Guide: 'client version is too new' API Version Mismatch

Exact Error Message

The Docker CLI prints this when it speaks a newer API version than the daemon it is talking to can understand:

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

Related wordings that all signal the same CLI-versus-daemon API mismatch:

Error response from daemon: client and server don't have same version (client API version: 1.45, server API version: 1.43)
request returned Internal Server Error for API route and version, check if the server supports the requested API version
client version 1.47 is too new. Maximum supported API version is 1.44

What It Means

Docker is a client/server system: the docker CLI sends HTTP requests to the daemon (dockerd) over a socket or TCP, and every request is tagged with an API version (for example 1.45). Each daemon advertises a maximum API version it supports. When the CLI’s negotiated version is higher than the daemon’s maximum, the daemon rejects the request with client version ... is too new.

This is purely a version-negotiation failure, not a connectivity or permissions problem — the CLI reached the daemon fine; the daemon simply cannot speak that dialect of the API. It almost always means the CLI is newer than the engine it is pointed at: a freshly upgraded CLI talking to an older dockerd, a Docker Desktop CLI talking to an older remote engine via DOCKER_HOST, or a CI runner whose docker binary outpaces the cluster’s daemon.

Normally the CLI and daemon perform automatic API-version negotiation on the first call: the client asks the daemon what it supports and downgrades to fit. That handshake is what keeps mixed versions working most of the time. The error appears when negotiation is bypassed — for example when DOCKER_API_VERSION is set to a fixed value in the environment, when a tool sends an explicit version, or when the daemon is so old it predates the version the CLI assumes as a floor. So the fix is almost never about networking; it is about making the client request a version the server actually advertises, either by letting negotiation happen or by pinning the right number yourself.

Common Causes

• CLI newer than the local daemon. The docker package was upgraded but dockerd was not (or vice versa).
• Remote DOCKER_HOST points at an older engine. Your modern CLI is driving an older daemon on a server, VM, or CI host.
• Docker Desktop vs standalone engine mismatch. Desktop’s bundled CLI talks to an older Engine you installed separately.
• CI image with a newer Docker than the build host’s daemon, e.g. docker-in-docker sidecars at mismatched versions.
• A podman-docker shim presenting an API version the docker CLI does not expect.
• A stale DOCKER_API_VERSION export left in a shell profile, Makefile, or CI variable that pins a version higher than the current daemon supports, defeating auto-negotiation.

How to Reproduce the Error

Force the CLI to request an API version newer than the daemon supports by exporting an override:

DOCKER_API_VERSION=1.99 docker ps

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

This mimics what happens naturally when a newer CLI auto-negotiates a version the older daemon cannot serve.

Diagnostic Commands

The single most useful command shows the client and server side by side — compare their API versions:

docker version

Client:
 Version:           27.0.3
 API version:       1.46
Server: Docker Engine - Community
 Engine:
  Version:          24.0.7
  API version:      1.43 (minimum version 1.24)

Here the client wants 1.46 but the server caps at 1.43 — that gap is the bug. You can also pull just the two numbers:

docker version --format 'client={{.Client.APIVersion}} server={{.Server.APIVersion}}'
docker info --format 'ServerVersion={{.ServerVersion}}'

Check which daemon you are even talking to (local socket vs remote) and the daemon’s own logs:

echo "DOCKER_HOST=$DOCKER_HOST DOCKER_API_VERSION=$DOCKER_API_VERSION"
journalctl -u docker --no-pager -n 30

Step-by-Step Resolution

1. Pin the API version as an immediate unblock. Force the CLI to request the daemon’s maximum so it stops over-negotiating:

export DOCKER_API_VERSION=1.43      # set to the server's "API version" from docker version
docker ps

Put it in your shell profile or CI environment for a durable fix without changing binaries.

2. Upgrade the daemon to match the CLI (the cleaner fix — it gains you the newer features the CLI expects):

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install --only-upgrade docker-ce docker-ce-cli
sudo systemctl restart docker
docker version

3. Match versions on remote/CI hosts. If DOCKER_HOST targets a remote engine, upgrade that engine, or pin DOCKER_API_VERSION to the remote’s maximum in the job environment.

4. Downgrade the CLI if you cannot touch the daemon (e.g. a locked-down production engine):

sudo apt-get install docker-ce-cli=5:24.0.7-1~ubuntu.22.04~jammy

5. Re-verify that both sides now agree:

docker version --format 'client={{.Client.APIVersion}} server={{.Server.APIVersion}}'

When the two API versions match (or the client’s is ≤ the server’s maximum), the error clears. If you set DOCKER_API_VERSION as a workaround, remember it is a floor-and-ceiling override that disables negotiation — once the daemon is upgraded you should unset it again, or a future newer daemon’s features will stay hidden from your CLI.

A quick mental model for choosing between the fixes: pin DOCKER_API_VERSION when you cannot change the daemon right now and just need commands to work; upgrade the daemon when you own it and want the newer API features; downgrade the CLI only when the daemon is deliberately frozen at an older version you are not allowed to touch. In CI, prefer pinning over downgrading so every job is reproducible regardless of which docker binary the base image ships.

How to Prevent the Issue

• Keep the CLI and engine on the same Docker version on every host; upgrade them together, not independently.
• Pin DOCKER_API_VERSION in CI pipelines and shared remote-host configs so a CLI upgrade cannot silently outrun an older daemon.
• When using docker-in-docker or remote DOCKER_HOST, document the engine version the runners must target and assert it at the start of the job (docker version --format ...).
• Treat a podman-docker shim as a version surface too — confirm its advertised API version matches what your tooling expects.
• Roll daemon upgrades out before, or together with, CLI upgrades so the server is never behind the client. See more in Docker guides.

Related Docker Errors

• Docker Error: cannot connect to the Docker daemon — when the CLI cannot reach the daemon at all, a different failure mode from a version mismatch (the connection itself fails rather than the API version).
• Docker Error: OCI runtime create failed — runtime-level failures that occur after the CLI and daemon agree on the API.
• Browse the full Docker troubleshooting category for more daemon and CLI error guides.