docker/cli · error

query parameters are not allowed

Error message

query parameters are not allowed: %q

What it means

Specific validation error from newSpec (ssh.go:63-64): the parsed ssh URL must not carry a query string. If u.RawQuery is non-empty, the raw query is echoed back and the Spec construction aborts. ssh connection options are not configurable via the URL.

Solutions

1. Remove the query string from the DOCKER_HOST ssh URL.
2. Configure ssh options in `~/.ssh/config` instead (e.g. a Host block with IdentityFile, ConnectTimeout).
3. If invoking the helper programmatically, pass extra ssh flags via GetConnectionHelperWithSSHOpts.

Example fix

# before
export DOCKER_HOST='ssh://user@host?ConnectTimeout=10'
# after — option lives in ~/.ssh/config
# Host host
#   ConnectTimeout 10
export DOCKER_HOST='ssh://user@host'

u, _ := url.Parse(daemonURL)
if u != nil && u.RawQuery != "" {
    return errors.New("ssh URL must not contain query parameters; use ~/.ssh/config")
}

spec, err := ssh.ParseURL(daemonURL)
if err != nil {
    return fmt.Errorf("ssh URL rejected: %w", err)
}

When it happens

Trigger: ssh.ParseURL or NewSpec receives a URL like `ssh://user@host?ConnectTimeout=10`. The presence of any `?...` triggers the error.

Common situations: A user tries to pass ssh options through the DOCKER_HOST URL (e.g. `?IdentityFile=...`, `?StrictHostKeyChecking=no`), which is unsupported. SSH options must be set via the normal ssh config / known_hosts / GetConnectionHelperWithSSHOpts flags, not the URL.

Related errors

• fragments are not allowed
• incorrect scheme:
• hostname is empty
• no remote command specified
• invalid SSH URL

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

Appendix: source

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

		return nil, errors.New("incorrect scheme: " + u.Scheme)
	}

	var sp Spec

	if u.User != nil {
		sp.User = u.User.Username()
		if _, ok := u.User.Password(); ok {
			return nil, errors.New("plain-text password is not supported")
		}
	}
	sp.Host = u.Hostname()
	if sp.Host == "" {
		return nil, errors.New("hostname is empty")
	}
	sp.Port = u.Port()
	sp.Path = u.Path
	if u.RawQuery != "" {
		return nil, fmt.Errorf("query parameters are not allowed: %q", u.RawQuery)
	}
	if u.Fragment != "" {
		return nil, fmt.Errorf("fragments are not allowed: %q", u.Fragment)
	}

	return &sp, nil
}

// Spec of SSH URL
type Spec struct {
	User string
	Host string
	Port string
	Path string
}

// Args returns args except "ssh" itself combined with optional additional
// command and args to be executed on the remote host. It attempts to quote

View on GitHub (pinned to 4f84911bfe)