docker/cli · error

invalid bind address format

Error message

invalid bind address format: %s

What it means

parseDockerDaemonHost accepts only the schemes tcp, unix, npipe, fd, and ssh. Any other scheme (or a non-empty token before '://' that is not one of these) reaches the default branch and is rejected. A bare host:port with no scheme is treated as tcp, so this specifically fires on an unrecognized scheme.

Solutions

1. Use one of the supported schemes: tcp://, unix://, npipe://, fd://, ssh://.
2. For raw host:port, omit the scheme — tcp is assumed.
3. For the Docker HTTP API use tcp://host:2375 (or 2376 for TLS), not http://.
4. Validate the scheme against the allow-list before passing the value to ParseHost.

Example fix

# before
docker -H http://127.0.0.1:2375 ps

# after
docker -H tcp://127.0.0.1:2375 ps

var hostSchemes = map[string]bool{"tcp": true, "unix": true, "npipe": true, "fd": true, "ssh": true}

func validDaemonHost(s string) error {
    if i := strings.Index(s, "://"); i >= 0 {
        if !hostSchemes[s[:i]] {
            return fmt.Errorf("unsupported scheme in %q", s)
        }
    }
    return nil
}

When it happens

Trigger: Passing -H with an unsupported protocol, e.g. -H foo://x, -H http://127.0.0.1:2375, or a garbage -H value that parses into an unknown scheme.

Common situations: Typo in the -H scheme; using http:// instead of tcp://; copy-pasting a URL with the wrong scheme; assuming a protocol the daemon does not support.

Related errors

• invalid proto, expected
• invalid proto, expected tcp
• invalid spec
• invalid count ( ): value must be either "all" or an integer
• gpu request key ' ' can be specified only once

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

Appendix: source

Thrown at opts/hosts.go:75

	proto, host, hasProto := strings.Cut(addr, "://")
	if !hasProto && proto != "" {
		host = proto
		proto = "tcp"
	}

	switch proto {
	case "tcp":
		return ParseTCPAddr(host, defaultTCPHost)
	case "unix":
		return parseSimpleProtoAddr(proto, host, defaultUnixSocket)
	case "npipe":
		return parseSimpleProtoAddr(proto, host, defaultNamedPipe)
	case "fd":
		return addr, nil
	case "ssh":
		return addr, nil
	default:
		return "", fmt.Errorf("invalid bind address format: %s", addr)
	}
}

// parseSimpleProtoAddr parses and validates that the specified address is a valid
// socket address for simple protocols like unix and npipe. It returns a formatted
// socket address, either using the address parsed from addr, or the contents of
// defaultAddr if addr is a blank string.
func parseSimpleProtoAddr(proto, addr, defaultAddr string) (string, error) {
	addr = strings.TrimPrefix(addr, proto+"://")
	if strings.Contains(addr, "://") {
		return "", fmt.Errorf("invalid proto, expected %s: %s", proto, addr)
	}
	if addr == "" {
		addr = defaultAddr
	}
	return fmt.Sprintf("%s://%s", proto, addr), nil
}

View on GitHub (pinned to 4f84911bfe)