juanfont/headscale · error

invalid prefix

Error message

invalid prefix

What it means

Prefix.Validate (hscontrol/policy/v2/types.go:647-652) wraps netip.Prefix.IsValid; any address/prefix token that Go's net/netip considers invalid (bad octets, malformed mask, non-IP text where an IP was required) is rejected with this sentinel including the raw string.

Source

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

// today. Each entry maps to the tracking issue an operator can follow. The
// caps are accepted by Tailscale SaaS, but delivering them via headscale
// without the matching server-side machinery would be misleading — nodes
// would advertise a feature that does not work. Reject at policy load and
// point operators at the issue.
var nodeAttrUnsupportedCaps = map[tailcfg.NodeCapability]string{
	tailcfg.NodeAttrFunnel: "https://github.com/juanfont/headscale/issues/2527",
}

// Policy validation errors.
var (
	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)")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Correct the CIDR to a valid dotted-quad plus legal mask length
2. Validate prefixes with 'ipcalc' or equivalent before pasting
3. Use /32 for single addresses instead of bare IPs where required

Example fix

// before
{"hosts": {"example-host": "10.0.0/32"}}
// after
{"hosts": {"example-host": "10.0.0.1/32"}}

if _, err := netip.ParsePrefix(cidr); err != nil {
    return fmt.Errorf("invalid prefix %q: %w", cidr, err)
}

func isValidPrefix(s string) bool { _, err := netip.ParsePrefix(s); return err == nil }

if errors.Is(err, policy.ErrInvalidPrefix) {
    // the wrapped value shows the bad CIDR; correct octets/mask
}

When it happens

Trigger: A hosts-map value or alias that parses as a prefix but is invalid — e.g. "10.0.0/32" (incomplete address), "10.0.0.0/33" (mask out of range), "100.100.100.256/32", or a bare malformed string like "10.0.0.0/24/24". Fails at parse or when Host.resolve validates the mapped prefix (types.go:632).

Common situations: Hand-editing CIDRs and dropping an octet; copying prefixes with unicode dashes; typo in netmask bits; pasting host entries with trailing characters.

Related errors

• test(s) failed
• tags in SSH source cannot access user-owned devices
• user destination requires source to contain only that same u
• autogroup:self destination requires source to contain only u
• tags in SSH source cannot access autogroup:member (user-owne

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