What causes "invalid port: %w" in docker/cli?

Inspect the port segment of the DOCKER_HOST URL for hidden/control characters.

invalid port

Error message

invalid port: %w

What it means

Raised in Spec.args (ssh.go:118-120) when the port portion of the ssh URL cannot be POSIX-shell-quoted by syntax.Quote. The port is taken from u.Port() and passed to ssh's `-p` flag; if it contains bytes the quoting library rejects, this wraps the error.

Solutions

Inspect the port segment of the DOCKER_HOST URL for hidden/control characters.
Set the port to a plain numeric value (1–65535).
Re-export DOCKER_HOST and retest.

Example fix

# before — control char in port
export DOCKER_HOST='ssh://user@host:22<x00>'
# after
export DOCKER_HOST='ssh://user@host:22'

Defensive patterns

Strategy: validation

Validate before calling

u, _ := url.Parse(daemonURL)
if port := u.Port(); port != "" {
    n, err := strconv.Atoi(port)
    if err != nil || n < 1 || n > 65535 {
        return errors.New("ssh URL port must be a number 1-65535")
    }
}

Try / catch

args, err := spec.Args(remote...)
if err != nil {
    return fmt.Errorf("cannot build ssh args (bad port?): %w", err)
}

Prevention

Only use numeric ports in the DOCKER_HOST ssh URL.
Sanitize env-sourced URL values for control characters.
Validate DOCKER_HOST in a startup check.

When it happens

Trigger: Spec.args/Args/Command is called after building a Spec from a URL whose Port field (the part after `:` in the authority) contains characters syntax.Quote cannot handle, such as a NUL or non-printable control character.

Common situations: A DOCKER_HOST ssh URL with a port like `ssh://user@host:22\x00` where a stray control byte leaked in from a misconfigured env var or script. Rare; normally the port is a clean integer.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/2976f139e8f15c0c. Report an issue: GitHub.

Appendix: source

Thrown at cli/connhelper/ssh/ssh.go:120

func (sp *Spec) args(sshFlags ...string) ([]string, error) {
	var args []string
	if sp.Host == "" {
		return nil, errors.New("no host specified")
	}
	if sp.User != "" {
		// Quote user, as it's obtained from the URL.
		usr, err := syntax.Quote(sp.User, syntax.LangPOSIX)
		if err != nil {
			return nil, fmt.Errorf("invalid user: %w", err)
		}
		args = append(args, "-l", usr)
	}
	if sp.Port != "" {
		// Quote port, as it's obtained from the URL.
		port, err := syntax.Quote(sp.Port, syntax.LangPOSIX)
		if err != nil {
			return nil, fmt.Errorf("invalid port: %w", err)
		}
		args = append(args, "-p", port)
	}

	// We consider "sshFlags" to be "trusted", and set from code only,
	// as they are not parsed from the DOCKER_HOST URL.
	args = append(args, sshFlags...)

	host, err := syntax.Quote(sp.Host, syntax.LangPOSIX)
	if err != nil {
		return nil, fmt.Errorf("invalid host: %w", err)
	}

	return append(args, "--", host), nil
}

// Command returns the ssh flags and arguments to execute a command
// (remoteCommandAndArgs) on the remote host. Where needed, it quotes

View on GitHub (pinned to 4f84911bfe)