juanfont/headscale · error

invalid auto approver format

Error message

invalid auto approver format

What it means

AutoApprovers parsing (hscontrol/policy/v2/types.go:1205) validates each auto-approver token in the autoApprovers section (routes/exitNode lists). A token that is not a valid approver alias — not a user, group, tag, or supported autogroup in the expected form — is rejected with this sentinel including the string.

Source

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

	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)")
	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")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Use identities as approvers: group:..., tag:..., user email, or a supported autogroup
2. Verify each autoApprovers entry resolves like a src-side alias
3. Check the parsed policy with 'headscale policy check'

Example fix

// before
{"autoApprovers": {"routes": {"10.0.0.0/8": ["10.0.0.1"]}}}
// after
{"autoApprovers": {"routes": {"10.0.0.0/8": ["group:admins"]}}}

func isValidApprover(s string) bool {
    return strings.HasPrefix(s, "group:") || strings.HasPrefix(s, "tag:") ||
        strings.Contains(s, "@") || strings.HasPrefix(s, "autogroup:")
}
for _, apps := range policy.AutoApprovers.Routes {
    for _, a := range apps { if !isValidApprover(a) { return fmt.Errorf("bad approver %q", a) } }
}

func isApproverToken(s string) bool { return isValidApprover(s) }

if errors.Is(err, policy.ErrInvalidAutoApprover) {
    // replace non-identity tokens with users/groups
}

When it happens

Trigger: {"autoApprovers": {"routes": {"10.0.0.0/8": ["bad token"]}}} where the entry has a wrong prefix, empty value, or an approver form the parser rejects (e.g. a hostname or CIDR, which cannot approve routes).

Common situations: Putting an IP or hostname in the approver list instead of an identity; typo'd group:/tag: prefix; assuming any dst-style alias is valid as an approver.

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/3fdac6b29b76b483. Report an issue: GitHub.