juanfont/headscale · error

invalid autogroup

Error message

invalid autogroup

What it means

AutoGroup parsing (hscontrol/policy/v2/types.go:748) accepts only autogroups in headscale's allowed set (the valid list is embedded in the error). A token starting with 'autogroup:' whose suffix is not in that set — e.g. autogroup:admin, autogroup:owner — fails at UnmarshalJSON with this sentinel, so the policy never reaches per-position validators.

Source

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

// 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)")
	ErrAutogroupNotSupported       = errors.New("autogroup not supported in headscale")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Use only the autogroups listed in the error message (self, member, tagged, internet, danger-all)
2. Replace autogroup:admin/owner with an explicit group of admin users
3. Consult headscale's ACL docs for the supported autogroup set

Example fix

// before
{"acls": [{"action": "accept", "src": ["autogroup:admin"], "dst": ["*:*"]}]}
// after
{"acls": [{"action": "accept", "src": ["group:admins"], "dst": ["*:*"]}]}

valid := map[string]bool{"autogroup:self": true, "autogroup:member": true, "autogroup:tagged": true, "autogroup:internet": true, "autogroup:danger-all": true}
if strings.HasPrefix(tok, "autogroup:") && !valid[tok] {
    return fmt.Errorf("unknown autogroup %q", tok)
}

func isValidAutogroup(s string) bool { return validAutogroups[s] }

if errors.Is(err, policy.ErrInvalidAutogroup) {
    // error message lists valid values; pick from it
}

When it happens

Trigger: Writing 'autogroup:admin' or 'autogroup:owner' anywhere in a policy (these exist in other Tailscale-flavoured grammars but not headscale's); any misspelled autogroup like 'autogroup:members'. Fails at parse time.

Common situations: Copying ACLs written for another control plane that supports admin/owner autogroups; assuming the Tailscale SaaS autogroup list applies verbatim to headscale.

Related errors

• nodeAttrs target does not support this autogroup
• test(s) failed
• autogroup:self destination requires source to contain only u
• tags in SSH source cannot access autogroup:member (user-owne
• username must contain @

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