docker / docker/cli

api-version negotiation sometimes fails over SSH connection

Open
#6,125 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

kind/bug status/0-triage version/28.2
Dominant language
Go
Stars
6.1k
Forks
2.2k
Avg merge
1d 15h
Merged PRs (30d)
43

Description

Description

API-version context negotiation seems to fail sometimes. In CI, this also shows with an error/warning (but in my reproduction steps, that didn't show for some reason, but possibly was suppressed by the output format)

Reproduce
docker context create --docker host=ssh://swarm-test-02 remote
remote
Successfully created context "remote"

The debug log comes from commandcon.New, so not 100% sure yet why it's triggered twice;
https://github.com/docker/cli/blob/9e506545fdead79c574345a0414c71a0bd6857d6/cli/connhelper/commandconn/commandconn.go#L34-L73

In this case it was run twice, and (see API version: 1.50) it didn't negotiate an API version;

docker context create --docker host=ssh://swarm-test-02 remote
remote
Successfully created context "remote"

docker --debug --context remote version
time="2025-06-10T14:29:31+02:00" level=debug msg="commandconn: starting ssh with [-o ConnectTimeout=30 -T -- swarm-test-02 docker system dial-stdio]"
time="2025-06-10T14:29:33+02:00" level=debug msg="commandconn: starting ssh with [-o ConnectTimeout=30 -T -- swarm-test-02 docker system dial-stdio]"
Client:
 Version:           28.2.2
 API version:       1.50
 Go version:        go1.24.3
 Git commit:        e6534b4
 Built:             Fri May 30 12:07:35 2025
 OS/Arch:           darwin/arm64
 Context:           remote

Server: Docker Engine - Community
 Engine:
  Version:          24.0.5
  API version:      1.43 (minimum version 1.12)
  Go version:       go1.20.6
  Git commit:       a61e2b4
  Built:            Fri Jul 21 20:35:23 2023
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.6.22
  GitCommit:        8165feabfdfe38c65b599c4993d227328c231fca
 runc:
  Version:          1.1.8
  GitCommit:        v1.1.8-0-g82f18fe
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

On a second attempt, it was only ran once, and did negotiate (API version: 1.43 (downgraded from 1.50));

docker --debug --context remote version
time="2025-06-10T14:30:05+02:00" level=debug msg="commandconn: starting ssh with [-o ConnectTimeout=30 -T -- swarm-test-02 docker system dial-stdio]"
Client:
 Version:           28.2.2
 API version:       1.43 (downgraded from 1.50)
 Go version:        go1.24.3
 Git commit:        e6534b4
 Built:             Fri May 30 12:07:35 2025
 OS/Arch:           darwin/arm64
 Context:           remote

Server: Docker Engine - Community
 Engine:
  Version:          24.0.5
  API version:      1.43 (minimum version 1.12)
  Go version:       go1.20.6
  Git commit:       a61e2b4
  Built:            Fri Jul 21 20:35:23 2023
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.6.22
  GitCommit:        8165feabfdfe38c65b599c4993d227328c231fca
 runc:
  Version:          1.1.8
  GitCommit:        v1.1.8-0-g82f18fe
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0
Expected behavior

No response

docker version
Client:
 Version:           28.2.2
 API version:       1.50
 Go version:        go1.24.3
 Git commit:        e6534b4
 Built:             Fri May 30 12:07:35 2025
 OS/Arch:           darwin/arm64
 Context:           remote
docker info
Likely not relevant
Additional Info

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with cli/connhelper/commandconn/commandconn.go at the commandcon.New path referenced in the issue, then reproduce the two docker --debug --context remote version runs over SSH. Compare why the SSH command starts twice and whether API negotiation is skipped; done means the remote version consistently negotiates and reports the server-compatible API version.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, go
Domain
cli, networking
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.