Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Docker client and daemon disagree on the API version

Errorrequest returned Internal Server Error for API route and version

Short answer

The client and the daemon speak different Docker API versions. Run docker version to see both numbers and the daemon's minimum. Upgrade the older side, or pin the client with DOCKER_API_VERSION. Docker Engine 29.0 to 29.2 required API 1.44, so older clients failed against it.

  • Applies to Docker Engine 28 and 29, Docker CLI 28 and 29
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the client and server sections. Compare the API version of each, and read the minimum the server accepts.

    docker version
  2. 2Match what you see, then jump to its fix

    1. 1Only an old client, SDK or tool fails; docker version works with the current CLIThe daemon requires a newer API than the client or tool usesFix
    2. 2The CLI is newer than the engine, for example after upgrading only the CLIThe client asks for a newer API than the daemon hasFix

What does the error look like?

  • request returned Internal Server Error for API route and version

Cause 1 of 2

The daemon requires a newer API than the client or tool uses

1Check

Docker Engine 29.0.0 raised the minimum API version to 1.44. Engine 29.3.0 lowered it to 1.40 again. A tool built for an older API fails against a daemon in between.

docker version

2Fix

Update the client or SDK, or move the engine to 29.3 or newer where the minimum is 1.40.

# after upgrading with your package manager, confirm the minimum API version
docker version

3Verify

docker version shows the new engine and commands work.

docker version && docker ps

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

The client asks for a newer API than the daemon has

1Check

A newer client may request endpoints an older daemon does not offer. Normally the client negotiates down to the highest version both support, and the page says negotiation is disabled when DOCKER_API_VERSION is set.

env | grep DOCKER_API_VERSION
docker version

2Fix

Unset a stale DOCKER_API_VERSION so negotiation works again, or set it to the daemon's API version if you must pin.

unset DOCKER_API_VERSION
# or pin to the server's version, taken from docker version
export DOCKER_API_VERSION=1.51

3Verify

The command that failed now runs.

docker ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Update the Docker CLI and the engine together.
  • Avoid exporting DOCKER_API_VERSION in shell profiles; use it only to debug.
  • Check the minimum API version in the release notes before upgrading the engine.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

The docker command cannot reach the Docker daemon

Cannot connect to the Docker daemon at unix:///Users/<user>/.docker/run/docker.sock. Is the docker daemon running?

This error means the docker client could not talk to a running daemon.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.