What causes "hostname contains invalid IP address" in juanfont/headscale?

Use a valid IP address or CIDR as the host value: "example-host-1": "100.100.100.100" or "10.0.0.0/24"

hostname contains invalid IP address

Error message

hostname contains invalid IP address

What it means

Returned by Hosts.UnmarshalJSON (hscontrol/policy/v2/types.go:1426) when the value of an entry in the policy's "hosts" map cannot be parsed as an IP address or prefix. Hosts are static DNS aliases mapping a name to an IP/CIDR; the value goes through Prefix.parseString and any parse failure is reported with the hostname and the invalid value.

Source

Thrown at hscontrol/policy/v2/types.go:126

	ErrInvalidUsername             = errors.New("username must contain @")
	ErrUserNotFound                = errors.New("user not found")
	ErrMultipleUsersFound          = errors.New("multiple users found")
	ErrInvalidGroupFormat          = errors.New("group must start with 'group:'")
	ErrInvalidTagFormat            = errors.New("tag must start with 'tag:'")
	ErrInvalidHostname             = errors.New("invalid hostname")
	ErrHostResolve                 = errors.New("error resolving host")
	ErrInvalidPrefix               = errors.New("invalid prefix")
	ErrInvalidAutogroup            = errors.New("invalid autogroup")
	ErrUnknownAutogroup            = errors.New("unknown autogroup")
	ErrHostportMissingColon        = errors.New("hostport must contain a colon")
	ErrTypeNotSupported            = errors.New("type not supported")
	ErrInvalidAlias                = errors.New("invalid alias format")
	ErrInvalidAutoApprover         = errors.New("invalid auto approver format")
	ErrInvalidOwner                = errors.New("invalid owner format")
	ErrGroupNotDefined             = errors.New("group not defined in policy")
	ErrInvalidGroupMember          = errors.New("invalid group member type")
	ErrGroupValueNotArray          = errors.New("group value must be an array of users")
	ErrInvalidHostIP               = errors.New("hostname contains invalid IP address")
	ErrTagNotDefined               = errors.New("tag not found")
	ErrAutoApproverNotAlias        = errors.New("auto approver is not an alias")
	ErrInvalidACLAction            = errors.New("invalid ACL action")
	ErrInvalidSSHAction            = errors.New("invalid SSH action")
	ErrInvalidProtocolNumber       = errors.New("invalid protocol number")
	ErrProtocolLeadingZero         = errors.New("leading 0 not permitted in protocol number")
	ErrProtocolOutOfRange          = errors.New("protocol number out of range (0-255)")
	ErrAutogroupNotSupported       = errors.New("autogroup not supported in headscale")
	ErrAutogroupInternetSrc        = errors.New("autogroup:internet can only be used in ACL destinations")
	ErrAutogroupSelfSrc            = errors.New("\"autogroup:self\" not valid on the src side of a rule")
	ErrAutogroupNotSupportedACLSrc = errors.New("autogroup not supported for ACL sources")
	ErrAutogroupNotSupportedACLDst = errors.New("autogroup not supported for ACL destinations")
	ErrAutogroupDangerAllDst       = errors.New("cannot use autogroup:danger-all as a dst")
	ErrAutogroupNotSupportedSSHSrc = errors.New("autogroup not supported for SSH sources")
	ErrAutogroupNotSupportedSSHDst = errors.New("autogroup not supported for SSH destinations")
	ErrHostNotDefined              = errors.New("host not defined in policy")
	ErrSSHSourceAliasNotSupported  = errors.New("alias not supported for SSH source")
	ErrSSHDestAliasNotSupported    = errors.New("alias not supported for SSH destination")

View on GitHub (pinned to 565fd254d0)

Solutions

Use a valid IP address or CIDR as the host value: "example-host-1": "100.100.100.100" or "10.0.0.0/24"
If you need a DNS name, put it on the left side and the IP on the right side; hosts entries cannot resolve domains
Check IPv6 entries include the full address form (e.g. "fd7a:115c:a1e0::1")

Example fix

// before
"hosts": {
  "example-host-1": "example.com"
}

// after
"hosts": {
  "example-host-1": "100.100.100.100"
}

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check every hosts value parses as a prefix
for name, val := range hostsMap {
	if _, err := netip.ParsePrefix(val); err != nil {
		if _, err2 := netip.ParseAddr(val); err2 != nil {
			return fmt.Errorf("host %s has invalid address %s", name, val)
		}
	}
}

Type guard

func isInvalidHostIP(err error) bool {
	return errors.Is(err, policy.ErrInvalidHostIP)
}

Try / catch

if err := json.Unmarshal(b, &p); err != nil {
	if errors.Is(err, policy.ErrInvalidHostIP) {
		// message names the hostname and bad value; surface to the operator
		return fmt.Errorf("invalid hosts entry: %w", err)
	}
	return err
}

Prevention

Never put DNS names on the right side of a hosts entry — hosts maps name -> IP/CIDR only
Generate hosts entries from IPAM data rather than hand-typing addresses
Run `headscale policy check` after editing hosts

When it happens

Trigger: A policy with "hosts": {"example-host-1": "not-an-ip"}, "hosts": {"h": "192.168.1"} (malformed octets), or a DNS name as the value ("hosts": {"alias": "example.com"} — dynamic resolution is not supported in hosts). Fails when the policy is loaded at startup or via `headscale policy set`.

Common situations: Expecting hosts entries to work like /etc/hosts with domain names on the right-hand side, typos in IPv6 addresses, or pasting a hostname where an IP is required. Users coming from other ACL systems that allow DNS targets hit this often.

Related errors

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/2a19442e75e55f8e. Report an issue: GitHub.