juanfont/headscale · error

autogroup not supported for ACL sources

Error message

autogroup not supported for ACL sources

What it means

Returned by validateAutogroupForSrc (hscontrol/policy/v2/types.go:2046) when an autogroup used as an ACL source is not in autogroupForSrc = {autogroup:member, autogroup:tagged, autogroup:danger-all} (types.go:1998). autogroup:internet and autogroup:self get their own specific errors first (2038/2042), so this fires for any other autogroup value that parses but is not a legal source.

Source

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

	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")
	ErrSSHTestEmptyDst             = errors.New("SSH tests entry must have at least one dst")
	ErrSSHTestDstUnknownTag        = errors.New("SSH tests dst contains unknown tag")
	ErrSSHTestDstDisallowedElement = errors.New("SSH tests dst contains disallowed element")

View on GitHub (pinned to 565fd254d0)

Solutions

  1. Read the allowed list in the error message ('can be [autogroup:member autogroup:tagged autogroup:danger-all]') and use one of those on src
  2. If you need 'all user-owned devices' use autogroup:member; 'all tagged devices' use autogroup:tagged; 'anything' use autogroup:danger-all
  3. Move the unsupported autogroup to dst if that is its legal position

Example fix

// before
{"action": "accept", "src": ["autogroup:some-new-group"], "dst": ["tag:api:443"]}

// after
{"action": "accept", "src": ["autogroup:member"], "dst": ["tag:api:443"]}
Defensive patterns

Strategy: validation

Validate before calling

srcAutogroups := map[string]bool{"autogroup:member": true, "autogroup:tagged": true, "autogroup:danger-all": true}
for _, s := range acl.Src {
	if strings.HasPrefix(s, "autogroup:") && !srcAutogroups[s] {
		return fmt.Errorf("%s not allowed as src", s)
	}
}

Type guard

func isAutogroupNotSupportedACLSrc(err error) bool {
	return errors.Is(err, policy.ErrAutogroupNotSupportedACLSrc)
}

Try / catch

if err := p.Validate(); err != nil {
	if errors.Is(err, policy.ErrAutogroupNotSupportedACLSrc) {
		// error message lists the legal src autogroups — follow it
		return fmt.Errorf("illegal src autogroup: %w", err)
	}
	return err
}

Prevention

When it happens

Trigger: An ACL src containing an autogroup outside the allowed trio. With the current AutoGroup parse set, internet/self are special-cased and member/tagged/danger-all pass, so this is largely a forward-compatibility guard that activates when new autogroups are introduced. The error message embeds the allowed list.

Common situations: A future headscale version adds a new autogroup legal only in dst; older policies or early adopters using it in src will see this. Also from hand-crafted Go Policies with experimental autogroup values.

Related errors

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