juanfont/headscale · error

autogroup:internet can only be used in ACL destinations

Error message

autogroup:internet can only be used in ACL destinations

What it means

Returned when autogroup:internet is used on the source side of an ACL rule (validateAutogroupForSrc, hscontrol/policy/v2/types.go:2038) or in SSH sources/destinations (types.go:2115, 2131). autogroup:internet expands to all non-private (non-RFC1918/CGNAT) addresses and only makes sense as an ACL destination ('reach the internet'); it is meaningless as a traffic source inside a tailnet.

Source

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

	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")
	ErrSSHTestEmptyDst             = errors.New("SSH tests entry must have at least one dst")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Move autogroup:internet to the dst side of an ACL rule: src [your nodes], dst ["autogroup:internet:*"]
2. Remove it from SSH src/dst entirely; SSH rules only operate on tailnet identities
3. If you meant 'all nodes', use autogroup:member (user-owned) or autogroup:tagged on the src side

Example fix

// before
{"action": "accept", "proto": "tcp", "src": ["autogroup:internet"], "dst": ["tag:proxy:443"]}

// after
{"action": "accept", "proto": "tcp", "src": ["tag:proxy"], "dst": ["autogroup:internet:443"]}

// autogroup:internet is legal ONLY in ACL dst
for _, acl := range acls {
	for _, s := range acl.Src {
		if s == "autogroup:internet" {
			return errors.New("autogroup:internet cannot be a src")
		}
	}
}

func isAutogroupInternetSrc(err error) bool {
	return errors.Is(err, policy.ErrAutogroupInternetSrc)
}

if err := p.Validate(); err != nil {
	if errors.Is(err, policy.ErrAutogroupInternetSrc) {
		return fmt.Errorf("move autogroup:internet to an ACL dst: %w", err)
	}
	return err
}

When it happens

Trigger: Policy with "acls": [{"action": "accept", "src": ["autogroup:internet"], "dst": [...]}], or "ssh": [{"src": ["autogroup:internet"], ...}] or an SSH dst of autogroup:internet (the SSH dst path also returns this same sentinel at types.go:2131).

Common situations: Misreading the autogroup's purpose and trying to write 'traffic from the internet can reach X' — headscale ACLs only govern traffic inside the tailnet plus egress, so inbound internet sourcing does not exist. Also from copy-pasting an internet-egress rule and flipping src/dst.

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
• "autogroup:self" not valid on the src side of a rule

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