juanfont/headscale · error

unknown autogroup

Error message

unknown autogroup

What it means

AutoGroup.resolve (hscontrol/policy/v2/types.go:825-828) is reached when the token parses as an autogroup from the allowed grammar set but headscale has no resolver for it in the position/context being compiled — i.e. it is syntactically known but not supported for that resolution path. The offending value is included in the wrapped error.

Source

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

// 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")
	ErrAutogroupInternetSrc        = errors.New("autogroup:internet can only be used in ACL destinations")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Check the error's included value and the headscale docs for where that autogroup is supported
2. Move the autogroup to a supported position (e.g. ACL dst for autogroup:internet)
3. Upgrade headscale if the autogroup is supported in a newer release

Example fix

// before
{"autoApprovers": {"routes": {"10.0.0.0/8": ["autogroup:danger-all"]}}}
// after
{"autoApprovers": {"routes": {"10.0.0.0/8": ["group:admins"]}}}

// gate autogroup usage by position before compile
if tok == "autogroup:internet" && position != "aclDst" {
    return fmt.Errorf("%s not supported at %s", tok, position)
}

null

if errors.Is(err, policy.ErrUnknownAutogroup) {
    // move the autogroup to a supported position or upgrade headscale
}

When it happens

Trigger: An autogroup that passes UnmarshalJSON but has no implementation in the resolving code path — typically newer autogroups accepted by the parser but not wired into headscale's resolver, or valid-in-one-position autogroups reaching an unsupported resolver. Fires at policy compile, distinct from the parse-time ErrInvalidAutogroup.

Common situations: headscale version skew: a policy written for a newer headscale that supports more autogroups; using an autogroup in a context (e.g. nodeAttrs, autoApprovers) where only a subset resolves.

Related errors

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

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