How to fix Error response from daemon: client version X.XX is too new. Maximum supported API version is X.XX in Docker

First, identify the version mismatch by checking both client and server API versions:

docker version

This displays both the Client and Server sections. Look for the "API version" lines:

Client:
 Version:           24.0.7
 API version:       1.43

Server:
 Version:           20.10.21
 API version:       1.41 (minimum version 1.12)

In this example, the client uses API 1.43 but the server only supports up to 1.41, so the client is too new for the daemon. Note the server's maximum supported version for the next step.

The quickest fix is to tell the client to use an older API version by setting the DOCKER_API_VERSION environment variable to the daemon's maximum supported version:

Linux/macOS (temporary):

export DOCKER_API_VERSION=1.41
docker ps  # Should work now

Linux/macOS (permanent):
Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

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

Windows PowerShell (temporary):

$env:DOCKER_API_VERSION="1.41"
docker ps

Windows PowerShell (permanent):

[Environment]::SetEnvironmentVariable("DOCKER_API_VERSION", "1.41", "User")

Replace "1.41" with the maximum API version your server supports (from docker version).

The best long-term solution is to upgrade your Docker Engine so its supported API version meets or exceeds the client's:

Linux (using apt):

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Linux (using yum/dnf):

sudo yum update docker-ce docker-ce-cli containerd.io

Docker Desktop (Windows/macOS):
1. Open Docker Desktop
2. Click the gear icon (Settings)
3. Go to "Software Updates"
4. Click "Check for updates" and install any available updates

Verify after upgrade:

docker version

The Server API version should now be at least as high as the Client API version.

If you cannot upgrade the daemon (e.g., shared infrastructure, production constraints), you can downgrade the CLI to match the daemon:

Using Docker's version-specific packages (Linux):

# List available versions
apt-cache madison docker-ce-cli

# Install specific version
sudo apt-get install docker-ce-cli=5:20.10.21~3-0~ubuntu-jammy

Using Docker binaries directly:
1. Visit https://download.docker.com/linux/static/stable/
2. Download the version matching your daemon
3. Extract and replace the docker binary

Note: Downgrading means losing access to newer features. Prefer setting DOCKER_API_VERSION or upgrading the daemon when possible.

If the error occurs with docker-compose, set the API version before running compose commands:

export DOCKER_API_VERSION=1.41
docker-compose up -d

For docker-compose v2 (Docker Compose plugin):

export DOCKER_API_VERSION=1.41
docker compose up -d

Using an .env file:
You cannot set the API version directly in the compose YAML, but you can keep it in an .env file:

# .env file in same directory as docker-compose.yml
DOCKER_API_VERSION=1.41

Then run:

docker-compose --env-file .env up -d

When connecting to remote Docker hosts running older versions:

Using DOCKER_HOST with API version:

export DOCKER_HOST=tcp://remote-host:2375
export DOCKER_API_VERSION=1.40
docker ps

Using Docker context:

# Create a context for the remote host
docker context create remote-server --docker "host=tcp://remote-host:2375"

# Set API version when using the context
export DOCKER_API_VERSION=1.40
docker --context remote-server ps

Docker Machine (if applicable):

# Upgrade the Docker Machine instance
docker-machine upgrade <machine-name>

# Or regenerate certificates
docker-machine regenerate-certs <machine-name>

For tools like Traefik, Portainer, Watchtower, or Docker SDKs, prefer API version negotiation, and fall back to pinning a version the daemon supports:

Traefik:
Add to your Traefik configuration:

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    # Force a specific API version (check Traefik docs for syntax)

Or upgrade Traefik to a version compatible with your Docker daemon.

Python docker SDK:

import docker

# Recommended: let the client auto-negotiate a compatible API version
client = docker.from_env()

# Or pin a version the daemon supports, passed at construction time
client = docker.from_env(version='1.41')

# Equivalent, when building the client explicitly
client = docker.DockerClient(
    base_url='unix://var/run/docker.sock',
    version='1.41',
)

Note: pass version when constructing the client. Assigning client.api.version after construction is not the supported way to set the API version.

Go SDK:

cli, err := client.NewClientWithOpts(
    client.FromEnv,
    client.WithAPIVersionNegotiation(),  // Auto-negotiate
)

General approach:
Check if the tool supports setting DOCKER_API_VERSION via environment variable or has a configuration option for API version.

In CI/CD environments, set the API version in your pipeline configuration:

GitLab CI (.gitlab-ci.yml):

variables:
  DOCKER_API_VERSION: "1.41"

build:
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t myapp .

GitHub Actions:

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      DOCKER_API_VERSION: "1.41"
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: docker build -t myapp .

Jenkins:

pipeline {
    environment {
        DOCKER_API_VERSION = '1.41'
    }
    stages {
        stage('Build') {
            steps {
                sh 'docker build -t myapp .'
            }
        }
    }
}

Best practice: Pin Docker versions in CI to avoid unexpected version mismatches.