juanfont/headscale · info

autogroup not supported in headscale

Error message

autogroup not supported in headscale

What it means

Returned by validateAutogroupSupported (hscontrol/policy/v2/types.go:2026) when an autogroup appears in the autogroupNotSupported deny-list. That list is currently EMPTY (types.go:2003: autogroupNotSupported = []AutoGroup{}), so this error is unreachable with the current codebase — it is a reserved hook for autogroups headscale may refuse to implement later.

Source

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

	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")
	ErrUnknownField                = errors.New("unknown field")
	ErrProtocolNoSpecificPorts     = errors.New("protocol does not support specific ports")
	ErrTestEmptyAssertions         = errors.New("test entry must have at least one of \"accept\" or \"deny\"")
	ErrTestProtocolNotAllowed      = errors.New("test protocol must be tcp, udp, sctp, or empty")
	ErrTestDestinationMultiPort    = errors.New("test destination port must be a single port")
	ErrTestDestinationCIDR         = errors.New("test destination must be a single host, not a CIDR range")
	ErrAutogroupInternetTestDst    = errors.New("autogroup:internet not valid as a test destination")
	ErrSSHTestEmptySrc             = errors.New("SSH tests entry must have a non-empty src")

View on GitHub (pinned to 565fd254d0)

Solutions

1. If you see this message at runtime, check which autogroup is named and consult the headscale release notes for newly unsupported autogroups
2. Replace the unsupported autogroup with an explicit group, tag, or user list
3. Upgrade or pin headscale to a version whose autogroup support matches your policy

func isAutogroupNotSupported(err error) bool {
	return errors.Is(err, policy.ErrAutogroupNotSupported)
}

if err := p.Validate(); err != nil {
	if errors.Is(err, policy.ErrAutogroupNotSupported) {
		// currently unreachable (deny-list empty); treat as version mismatch
		return fmt.Errorf("autogroup unsupported in this headscale build: %w", err)
	}
	return err
}

When it happens

Trigger: Cannot be triggered by any policy today. Would fire if a future headscale release added an autogroup to autogroupNotSupported and a policy used it in an ACL src/dst or SSH position that routes through validateAutogroupSupported.

Common situations: Grep/error-catalog work: finding this sentinel with no call path producing it. Users seeing an 'autogroup not supported in headscale' message are most likely on a different headscale version or hitting a different autogroup error.

Related errors

• invalid SSH action
• autogroup:self requires per-node resolution and cannot be re
• 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

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