What causes "fragments are not allowed: %q" in docker/cli?

Strip the `#...` fragment from the DOCKER_HOST ssh URL.

fragments are not allowed

Error message

fragments are not allowed: %q

What it means

Specific validation error from newSpec (ssh.go:66-67): the parsed ssh URL must not carry a URL fragment. If u.Fragment is non-empty, the fragment is echoed back and Spec construction aborts. Fragments have no meaning for an ssh connection target.

Solutions

Strip the `#...` fragment from the DOCKER_HOST ssh URL.
Re-paste the URL from a plain-text source without the trailing fragment.
Re-set DOCKER_HOST and retest.

Example fix

# before
export DOCKER_HOST='ssh://user@host#docker'
# after
export DOCKER_HOST='ssh://user@host'

Defensive patterns

Strategy: validation

Validate before calling

u, _ := url.Parse(daemonURL)
if u != nil && u.Fragment != "" {
    return errors.New("ssh URL must not contain a fragment")
}

Try / catch

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

Prevention

Strip any trailing `#...` from pasted DOCKER_HOST values.
Paste URLs from plain text, not browser address bars.
Add a CI lint that rejects DOCKER_HOST values containing `#`.

When it happens

Trigger: ssh.ParseURL or NewSpec receives a URL like `ssh://user@host#section`. Any `#...` triggers the error.

Common situations: A URL is copy-pasted from documentation or a browser that appended a fragment (`#main`, `#docker`), or a user mistakenly adds a section anchor to DOCKER_HOST. Fragments are silently ignored by browsers but explicitly rejected here.

Related errors

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

Appendix: source

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

	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
// the given arguments to account for ssh executing the remote command in a
// shell. It returns nil when unable to quote the remote command.
func (sp *Spec) Args(remoteCommandAndArgs ...string) []string {

View on GitHub (pinned to 4f84911bfe)