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

What this error means

The Docker CLI and Docker Engine (daemon) communicate through a versioned HTTP API. When you run a Docker command, the client attempts to use a specific API version to talk to the daemon. This error appears when the client's API version is higher than the maximum version the daemon can handle — in other words, the daemon is too old for the client. This situation commonly occurs after upgrading the Docker CLI without updating the Docker Engine, when connecting to a remote Docker host running an older version, or when using newer tools (like docker-compose or Traefik) that target a newer API than your older daemon exposes. The API version is tied to specific Docker Engine releases; for example, API v1.44 corresponds to Docker Engine v25.0. The direction matters: "client version is too new" means you must point the client at a lower API version (or upgrade the daemon). It is the opposite of "client version is too old", which is about a client falling below the daemon's minimum supported API version.

Typical symptoms

• Docker commands fail with 'client version X.XX is too new' error
• docker-compose commands fail after upgrading Docker CLI
• CI/CD pipelines fail with API version mismatch errors
• Tools like Traefik, Portainer, or Watchtower fail to connect to Docker
• 'docker version' shows a higher API version for Client than for Server
• Remote Docker connections fail from a newer local machine
• Python docker SDK or other Docker libraries throw version errors

Common causes

1. Docker CLI version is newer than the Docker Engine/daemon version
2. Connecting to a remote Docker host running an older Docker version
3. Docker Desktop or Engine was not updated after a CLI upgrade
4. Using a newer docker-compose with an older Docker daemon
5. Docker SDK/library version mismatch with the target daemon
6. Third-party tools compiled against newer Docker API versions
7. Docker Machine pointing to an outdated Docker host
8. Container orchestration tools using incompatible API versions

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

docker version

Client:
 Version:           24.0.7
 API version:       1.43

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

export DOCKER_API_VERSION=1.41
docker ps  # Should work now

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

$env:DOCKER_API_VERSION="1.41"
docker ps

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

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

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

docker version

# 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

export DOCKER_API_VERSION=1.41
docker-compose up -d

export DOCKER_API_VERSION=1.41
docker compose up -d

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

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

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

# 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

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

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

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

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',
)

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

variables:
  DOCKER_API_VERSION: "1.41"

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

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

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

Advanced notes

Frequently asked questions

What does "Error response from daemon: client version X.XX is too new. Maximum su" mean?

The Docker CLI and Docker Engine (daemon) communicate through a versioned HTTP API. When you run a Docker command, the client attempts to use a specific API version to talk to the daemon. This error appears when the client's API version is higher than the maximum version the daemon can handle — in other words, the daemon is too old for the client.

How do I fix "Error response from daemon: client version X.XX is too new. Maximum su"?

This error occurs when your Docker client uses a newer API version than the daemon it is talking to can support. The fix is to lower the client's API version with DOCKER_API_VERSION, rely on API negotiation, or upgrade the daemon to match the client.

What causes "Error response from daemon: client version X.XX is too new. Maximum su"?

Docker CLI version is newer than the Docker Engine/daemon version Connecting to a remote Docker host running an older Docker version Docker Desktop or Engine was not updated after a CLI upgrade

Is the "Error response from daemon: client version X.XX is too new. Maximum su" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• ERROR: unable to select packages: pkg (no such package)

  How to fix 'unable to select packages: no such package' in Alpine Docker

  MEDIUM

• Error response from daemon: client version X.XX is too old. Minimum supported API version is X.XX

  How to fix 'client version is too old. Minimum supported API version' in Docker

  MEDIUM

• Error response from daemon: error loading AppArmor profile

  How to fix 'error loading AppArmor profile' in Docker

  MEDIUM

• Error starting userland proxy: listen tcp4 0.0.0.0:3000: bind: address already in use

  How to fix "address already in use" in Docker

  MEDIUM

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Docker Engine API - Docker Docs(Official Docs)
• 📖
  Engine API version history - Docker Docs(Official Docs)
• 📖
  Docker SDK - Docker Docs(Official Docs)
• 📖
  Docker Engine version 29 release notes - Docker Docs(Official Docs)
• 📖
  docker version command - Docker Docs(Official Docs)
• 💬
  Error response from daemon: client version 1.40 is too new - Stack Overflow(Stack Overflow)
• 💬
  docker-compose: client version is too new - Stack Overflow(Stack Overflow)
• 💬
  docker api client/server version mismatch - Stack Overflow(Stack Overflow)
• 💬
  Docker 29 increased minimum API version, breaks Traefik - Docker Forums(Stack Overflow)
• 📝
  Docker Engine v29 Release - Docker Blog
• 🐙
  Traefik fails with docker client version is too new - GitHub Issue #12279(GitHub)
• 📝
  Fix Docker client is newer than server version error - KhueApps
• 📖
  Docker API Version Mismatch Errors in CI/CD Pipelines - GitLab(Official Docs)