Fixing Docker's 'Client Is Newer Than Server' API Error

Why This Error Happens

It usually starts with a routine command. You run docker ps or docker-compose up, and instead of seeing your containers, you get a version mismatch error. This happens because Docker uses a client-server architecture. The Client is your terminal tool, and the Server (the Daemon) is the engine running the containers.

These two talk via a REST API. If you recently updated Docker Desktop to version 4.28 or higher, your client likely upgraded to API version 1.44. However, if your remote server is running an older version like Docker 20.10.x, it only understands API 1.41. The server rejects the connection because it doesn't recognize the newer features the client is trying to use.

Solution 1: Force the Client to Use an Older API

The fastest fix doesn't require any installations. You can tell your Docker CLI to "talk down" to the server's level. Docker is designed to be backward compatible, so this is safe and effective.

Linux and macOS

Set the environment variable for your current terminal session like this:

export DOCKER_API_VERSION=1.41

To make this stick, add it to your shell profile. For Zsh users, run this command:

echo 'export DOCKER_API_VERSION=1.41' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell)

If you are working in PowerShell, use this command for a temporary fix:

$env:DOCKER_API_VERSION = "1.41"

For a permanent change, open the Start menu and search for "Edit the system environment variables." Add a new variable named DOCKER_API_VERSION with the value 1.41.

Solution 2: Upgrade the Docker Engine

If you have SSH access to the server, upgrading the engine is the best long-term move. This ensures you have the latest security patches and performance improvements. On an Ubuntu or Debian server, it takes about 30 seconds:

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
sudo systemctl restart docker

Once updated, the server will support the newer API, and the error will vanish.

Solution 3: Handling Docker Compose V2

Modern Docker Compose (the docker compose command) usually respects the DOCKER_API_VERSION variable automatically. If you are still using the old, standalone docker-compose binary, it might behave differently. We recommend switching to the Docker Compose V2 plugin to avoid these legacy headaches.

Verification: Did it work?

Check the status of your connection by running:

docker version

Look at the API version fields. Both the Client and Server should now show compatible numbers. If you see 1.41 for both, you are good to go.

Client:
 API version:  1.41

Server:
 Engine:
  API version: 1.41 (minimum version 1.12)

Pro Tips for Prevention

• Match your environments: Try to keep your local Docker version within one or two minor releases of your production servers.
• CI/CD Alignment: If your GitHub Actions or GitLab runners fail with this error, check the docker-image version used in your pipeline YAML.
• Project-specific versions: You can drop a .env file into your project folder with COMPOSE_API_VERSION=1.41. This forces everyone on the team to use the same API version for that specific project.