What causes "invalid host name format" in containerd/containerd?

Fix the registry address to include a hostname (e.g. 'localhost:5000' instead of ':5000')

invalid host name format

Error message

invalid host name format

What it means

MatchLocalhost checks whether a registry host is a localhost address (to allow skipping TLS, mirroring Docker's registry matching). The host portion must be non-empty after splitting off the port; an empty host (e.g. input like ':5000' or '') yields this error.

Source

Thrown at core/remotes/docker/registry.go:242

	}
	h, p, err := net.SplitHostPort(host)

	// addrError helps distinguish between errors of form
	// "no colon in address" and "too many colons in address".
	// The former is fine as the host string need not have a
	// port. Latter needs to be handled.
	addrError := &net.AddrError{
		Err:  "missing port in address",
		Addr: host,
	}
	if err != nil {
		if err.Error() != addrError.Error() {
			return false, err
		}
		// host string without any port specified
		h = host
	} else if len(p) == 0 {
		return false, errors.New("invalid host name format")
	}

	// use ipv4 dotted decimal for further checking
	if h == "localhost" {
		h = "127.0.0.1"
	}
	ip := net.ParseIP(h)

	return ip.IsLoopback(), nil
}

func DefaultHTTPTransport(defaultTLSConfig *tls.Config) *http.Transport {
	return &http.Transport{
		Proxy: http.ProxyFromEnvironment,
		DialContext: (&net.Dialer{
			Timeout:       30 * time.Second,
			KeepAlive:     30 * time.Second,
			FallbackDelay: 300 * time.Millisecond,

View on GitHub (pinned to 4246446a2b)

Solutions

Fix the registry address to include a hostname (e.g. 'localhost:5000' instead of ':5000')
Validate the endpoint URL before configuring containerd (url.Parse and check u.Host != "")
Check hosts.toml / mirror config for missing or empty server hostnames
If parsing user input, reject empty-host URLs at the config-loading boundary

Example fix

// before
MatchLocalhost(":5000") // invalid host name format
// after
u, _ := url.Parse("http://localhost:5000")
MatchLocalhost(u.Host) // "localhost:5000" -> true

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(endpoint)
if err != nil || u.Host == "" {
    return fmt.Errorf("registry endpoint must include hostname: %q", endpoint)
}

Try / catch

isLocal, err := registry.MatchLocalhost(addr)
if err != nil && strings.Contains(err.Error(), "invalid host name format") {
    return fmt.Errorf("bad registry address %q: include a hostname", addr)
}

Prevention

Always configure full host:port for registry endpoints in hosts.toml
Validate endpoint URLs at config load time
Reject port-only or empty hostnames from user input

When it happens

Trigger: Calling MatchLocalhost with a URL/addr whose host part is empty — e.g. an address of form ':5000', a URL missing the host, or a registry endpoint configured with only a port.

Common situations: Typo'd registry config in hosts.toml / containerd config (missing hostname); parsing URLs where Host field wasn't populated; programmatic calls passing port-only strings.

Related errors

AI-assisted analysis of containerd/containerd@4246446a2b (2026-09-02). Data as JSON: /api/errors/355b6e2dd689ef59. Report an issue: GitHub.