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

First, identify exactly which API versions your client and server support:

docker version

This shows both client and server versions with their API versions:

Client:
 Version:           24.0.7
 API version:       1.43
 ...

Server:
 Engine:
  Version:          29.0.0
  API version:      1.48 (minimum version 1.44)
  ...

In this example, the client supports API 1.43 but the server requires minimum 1.44, causing the error.

If docker version itself fails, the client cannot even negotiate with the server. Check what version you have:

docker --version
which docker

The cleanest solution is to update your Docker client to a version that supports the required API.

On Linux (Ubuntu/Debian):

# Update package list and upgrade Docker
sudo apt-get update
sudo apt-get install --only-upgrade docker-ce docker-ce-cli containerd.io

# Verify the upgrade
docker version

On Linux (CentOS/RHEL/Fedora):

sudo dnf upgrade docker-ce docker-ce-cli containerd.io
# or
sudo yum upgrade docker-ce docker-ce-cli containerd.io

On macOS/Windows (Docker Desktop):

Update Docker Desktop through the application's update mechanism or download the latest version from https://www.docker.com/products/docker-desktop

For CI/CD pipelines:

Update your Docker client image to match the server:

# GitLab CI example - pin to a compatible version
image: docker:29.0
services:
  - docker:29.0-dind

If you cannot update all clients (e.g., third-party tools), configure the Docker daemon to accept older API versions.

Method A: Edit daemon.json

# Create or edit daemon.json
sudo nano /etc/docker/daemon.json

Add or merge in this configuration:

{
  "min-api-version": "1.24"
}

Use the API version your clients require. Common values:
- 1.24 - Supports Docker 1.12+
- 1.40 - Supports Docker 19.03+
- 1.41 - Supports Docker 20.10+
- 1.43 - Supports Docker 24.0+

Restart Docker:

sudo systemctl restart docker

Verify the change:

docker version
# Should show: API version: 1.48 (minimum version 1.24)

For Docker Desktop (macOS/Windows):

Go to Settings -> Docker Engine and add "min-api-version": "1.24" to the JSON configuration.

Method B: Systemd environment variable

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/min-api-version.conf << 'EOF'
[Service]
Environment="DOCKER_MIN_API_VERSION=1.24"
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

Force the Docker client to use a specific API version by setting an environment variable. This is useful for temporary fixes or debugging.

For single commands:

DOCKER_API_VERSION=1.44 docker ps
DOCKER_API_VERSION=1.44 docker-compose up

For your shell session:

export DOCKER_API_VERSION=1.44
docker ps  # Now uses API 1.44

In CI/CD pipelines (GitLab example):

variables:
  DOCKER_API_VERSION: "1.44"

build:
  script:
    - docker build -t myapp .

In docker-compose.yml:

services:
  myservice:
    environment:
      - DOCKER_API_VERSION=1.44

Important: This only works if the client supports the specified version. Setting a version higher than your client supports will fail.

If you need immediate compatibility and cannot update clients, you can temporarily downgrade the Docker daemon.

On Ubuntu/Debian:

# List available versions
apt-cache madison docker-ce

# Downgrade to a specific version (e.g., 28.0.4)
sudo apt-get install docker-ce=5:28.0.4-1~ubuntu.22.04~jammy docker-ce-cli=5:28.0.4-1~ubuntu.22.04~jammy

# Hold the version to prevent auto-upgrade
sudo apt-mark hold docker-ce docker-ce-cli

On CentOS/RHEL:

# List available versions
yum list docker-ce --showduplicates

# Downgrade
sudo yum downgrade docker-ce-28.0.4 docker-ce-cli-28.0.4

# Hold the version
sudo yum versionlock docker-ce docker-ce-cli

For Docker-in-Docker in CI/CD:

Pin to a specific version instead of using :latest or :dind:

services:
  - docker:28.0.4-dind

Warning: Downgrading is a temporary measure. Plan to update your clients to maintain security patches and new features.

Popular container management tools may need updates or configuration changes.

Traefik:

Traefik versions before 3.3.6 / 2.11.18 use API v1.24 by default. Either:

1. Update Traefik to the latest version (recommended)
2. Lower daemon's min-api-version to 1.24
3. Traefik 3.3.6+ supports API version negotiation

# docker-compose.yml for Traefik
services:
  traefik:
    image: traefik:v3.3.6  # or newer

Portainer:

Update to the latest Portainer version:

docker pull portainer/portainer-ce:latest
# Restart your Portainer container

Testcontainers:

Update your Testcontainers dependency to the latest version:

<!-- Maven -->
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers</artifactId>
    <version>1.21.0</version> <!-- Use latest -->
</dependency>

// Gradle
testImplementation 'org.testcontainers:testcontainers:1.21.0'

Docker SDK for Python/Go/Node.js:

Update to the latest SDK version that supports API negotiation.

After applying your chosen solution, verify everything works:

# Check versions
docker version

# Test basic operations
docker ps
docker images
docker pull hello-world
docker run --rm hello-world

# Check daemon configuration
docker info | grep -i "api version"

For CI/CD pipelines:

Run a test pipeline to ensure all Docker operations work correctly.

For third-party tools:

- Check Traefik logs: docker logs traefik
- Check Portainer can connect to Docker
- Run your Testcontainers test suite

If issues persist:

Check for multiple Docker installations or cached client binaries:

which -a docker
type docker

Ensure you're using the correct Docker binary and that no old versions remain in your PATH.