Repository navigation
Automatically negotiate API version to use #2547
Description
The go client has an option to automatically negotiate what API version should be selected.
This could also be used here.
Fork example calling `/version` returns the following:
{
"Platform" : {
"Name" : "Docker Desktop 4.51.0 (210443)"
},
"Components" : [ {
"Name" : "Engine",
"Version" : "28.5.2",
"Details" : {
"ApiVersion" : "1.51",
"Arch" : "amd64",
"BuildTime" : "2025-11-05T14:43:25.000000000+00:00",
"Experimental" : "false",
"GitCommit" : "89c5e8f",
"GoVersion" : "go1.25.3",
"KernelVersion" : "6.6.87.2-microsoft-standard-WSL2",
"MinAPIVersion" : "1.24",
"Os" : "linux"
}
}, {
"Name" : "containerd",
"Version" : "v1.7.29",
"Details" : {
"GitCommit" : "442cb34bda9a6a0fed82a2ca7cade05c5c749582"
}
}, {
"Name" : "runc",
"Version" : "1.3.3",
"Details" : {
"GitCommit" : "v1.3.3-0-gd842d771"
}
}, {
"Name" : "docker-init",
"Version" : "0.19.0",
"Details" : {
"GitCommit" : "de40ad0"
}
} ],
"Version" : "28.5.2",
"ApiVersion" : "1.51",
"MinAPIVersion" : "1.24",
"GitCommit" : "89c5e8f",
"GoVersion" : "go1.25.3",
"Os" : "linux",
"Arch" : "amd64",
"KernelVersion" : "6.6.87.2-microsoft-standard-WSL2",
"BuildTime" : "2025-11-05T14:43:25.000000000+00:00"
}
{
"Platform" : {
"Name" : "Docker Desktop 4.52.0 (210994)"
},
"Components" : [ {
"Name" : "Engine",
"Version" : "29.0.1",
"Details" : {
"ApiVersion" : "1.52",
"Arch" : "amd64",
"BuildTime" : "2025-11-14T16:17:57.000000000+00:00",
"Experimental" : "false",
"GitCommit" : "198b5e3",
"GoVersion" : "go1.25.4",
"KernelVersion" : "6.6.87.2-microsoft-standard-WSL2",
"MinAPIVersion" : "1.44",
"Os" : "linux"
}
}, {
"Name" : "containerd",
"Version" : "v2.1.5",
"Details" : {
"GitCommit" : "fcd43222d6b07379a4be9786bda52438f0dd16a1"
}
}, {
"Name" : "runc",
"Version" : "1.3.3",
"Details" : {
"GitCommit" : "v1.3.3-0-gd842d771"
}
}, {
"Name" : "docker-init",
"Version" : "0.19.0",
"Details" : {
"GitCommit" : "de40ad0"
}
} ],
"Version" : "29.0.1",
"ApiVersion" : "1.52",
"MinAPIVersion" : "1.44",
"GitCommit" : "198b5e3",
"GoVersion" : "go1.25.4",
"Os" : "linux",
"Arch" : "amd64",
"KernelVersion" : "6.6.87.2-microsoft-standard-WSL2",
"BuildTime" : "2025-11-14T16:17:57.000000000+00:00"
}
The MinAPIVersion attribute could be used to compare it with the client's version.
If ClientAPIVersion < MinAPIVersion the client could log an warning and force the use of MinAPIVersion - this should prevent hard errors at the cost that the API might be incompatible and not work 100%.
The same can also be done the other way around if ClientAPIVersion > ApiVersion.
NOTE: It's currently possible to just omit the /<version> prefix from the paths.
However using the API without a version-prefix is deprecated and will be removed in a future release.
Reacted by msc-xdev, Alex "Blex" B, János Csorvási, Jacek Bilski, Simon Templer, John Kelly and Nicklas Jensen
Activity
postalservice14 commentedon May 20, 2026
Hitting this on macOS Docker Desktop 4.74.0 (Engine 29.4.3, ApiVersion 1.54, MinAPIVersion 1.40), via Testcontainers 2.0.5 → docker-java 3.7.1.
Default config fails with the expected message:
Curl against /var/run/docker.sock works fine and reports those versions; the daemon is healthy. Setting DOCKER_API_VERSION=1.43 (or 1.50) avoids the "1.32 is too old" rejection but the Info call then returns a different HTTP 400 with a stubbed response body — possibly a separate Docker Desktop quirk on macOS, but worth flagging in case it points at the same code path that needs negotiation.
Reproducer: PostgreSQLContainer.start() inside a JUnit 5 / Spring Boot 4
@DataJpaTest. Auto-negotiation as proposed in this issue would resolve this completely.