docker/cli · error

hostname is empty

Error message

hostname is empty

What it means

Returned by newSpec when u.Hostname() returns an empty string. An SSH connection needs a target host to dial; without one the generated ssh command line would be incomplete and the connection could not be established.

Solutions

1. Provide a hostname: 'ssh://user@remote-host'.
2. If a port is needed, include the host: 'ssh://user@remote-host:2222'.
3. Check that any variable used for the host is non-empty before constructing the URL.

Example fix

# before
DOCKER_HOST=ssh://
# after
DOCKER_HOST=ssh://user@remote-host

u, err := url.Parse(host)
if err != nil || u.Hostname() == "" {
    return errors.New("DOCKER_HOST must include a hostname for ssh://")
}

func hasHostname(s string) bool {
    u, err := url.Parse(s)
    return err == nil && u.Hostname() != ""
}

When it happens

Trigger: Passing a URL like 'ssh:///path' (scheme but no host) or 'ssh://:22' (only a port). A URL that degenerates after parsing so the host portion is empty.

Common situations: Typing 'ssh://' without a hostname. A templated DOCKER_HOST whose host variable expanded to empty. Confusing an ssh URL with a unix socket path syntax.

Related errors

• incorrect scheme:
• no scheme provided
• plain-text password is not supported
• no remote command specified
• ssh host connection is not valid

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

Appendix: source

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

	}
	if u.Scheme == "" {
		return nil, errors.New("no scheme provided")
	}
	if u.Scheme != "ssh" {
		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

View on GitHub (pinned to 4f84911bfe)