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. 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:

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.

The best long-term solution is to upgrade your Docker Engine to match or exceed the client version:

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

Both Client and Server API versions should now be compatible.

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

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. Consider upgrading the daemon instead 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

In docker-compose.yml (for some versions):
You cannot directly set the API version in the compose file, but you can use 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 with 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:

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
client = docker.DockerClient(
    base_url='unix://var/run/docker.sock',
    version='1.41'  # Specify compatible API version
)

# Or use auto-negotiation (recommended)
client = docker.from_env()
client.api.version = '1.41'

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.