docker/cli · error

ssh host connection is not valid: %w

Error message

ssh host connection is not valid: %w

What it means

Error "ssh host connection is not valid: %w" thrown in docker/cli.

Source

Thrown at cli/connhelper/connhelper.go:50

// GetConnectionHelperWithSSHOpts returns Docker-specific connection helper for
// the given URL, and accepts additional options for ssh connections. It returns
// nil without error when no helper is registered for the scheme.
//
// Requires Docker 18.09 or later on the remote host.
func GetConnectionHelperWithSSHOpts(daemonURL string, sshFlags []string) (*ConnectionHelper, error) {
	return getConnectionHelper(daemonURL, sshFlags)
}

func getConnectionHelper(daemonURL string, sshFlags []string) (*ConnectionHelper, error) {
	u, err := url.Parse(daemonURL)
	if err != nil {
		return nil, err
	}
	if u.Scheme == "ssh" {
		sp, err := ssh.NewSpec(u)
		if err != nil {
			return nil, fmt.Errorf("ssh host connection is not valid: %w", err)
		}
		sshFlags = addSSHTimeout(sshFlags)
		sshFlags = disablePseudoTerminalAllocation(sshFlags)

		remoteCommand := []string{"docker", "system", "dial-stdio"}
		socketPath := sp.Path
		if strings.Trim(sp.Path, "/") != "" {
			remoteCommand = []string{"docker", "--host=unix://" + socketPath, "system", "dial-stdio"}
		}
		sshArgs, err := sp.Command(sshFlags, remoteCommand...)
		if err != nil {
			return nil, err
		}
		return &ConnectionHelper{
			Dialer: func(ctx context.Context, network, addr string) (net.Conn, error) {
				return commandconn.New(ctx, "ssh", sshArgs...)
			},
			Host: "http://docker.example.com",

View on GitHub (pinned to e9452d6e78)

When it happens

Trigger: Thrown at cli/connhelper/connhelper.go:50 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/3ab6be90ea47e208.json. Report an issue: GitHub.