juanfont/headscale · error

invalid ACL action

Error message

invalid ACL action

What it means

Returned by Action.UnmarshalJSON (hscontrol/policy/v2/types.go:1613) when an ACL rule's "action" field is anything other than "accept". Headscale ACLs are allow-only (absence of a matching rule means deny), matching Tailscale's grants model; the sentinel is wrapped as `action=%q is not supported` so the offending value is shown.

Source

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

	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")
	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\"")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Remove deny rules entirely — headscale policies are default-deny, only list what you allow
2. Check spelling and case: the only valid value is exactly "accept"
3. If you had a deny override, restructure by making the more specific accept rules not match that traffic

Example fix

// before
"acls": [
  {"action": "accept", "src": ["group:admin"], "dst": ["*:*"]},
  {"action": "deny", "src": ["*"], "dst": ["tag:server:22"]}
]

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

// Only 'accept' is valid for ACL actions
for _, acl := range rawAcls {
	if act := strings.TrimSpace(acl["action"]); act != "accept" {
		return fmt.Errorf("acls action must be 'accept', got %q", act)
	}
}

func isInvalidACLAction(err error) bool {
	return errors.Is(err, policy.ErrInvalidACLAction)
}

if err := json.Unmarshal(b, &p); err != nil {
	if errors.Is(err, policy.ErrInvalidACLAction) {
		// wrapped message shows action=%q; drop deny rules, policies are allow-only
		return fmt.Errorf("bad ACL action (policies are allow-only): %w", err)
	}
	return err
}

When it happens

Trigger: Policy with "acls": [{"action": "deny", "src": [...], "dst": [...]}], or a typo like "Accept"/"allow"/"permit". Fires during JSON unmarshalling, i.e. at policy load, before any other validation runs.

Common situations: Copy-pasting a firewall-style ruleset that mixes allow/deny rules; migrating from iptables-style thinking; users expecting explicit deny semantics. Any deny intent must be expressed by simply not granting access.

Related errors

• test(s) failed
• nodeAttrs target does not support this autogroup
• username must contain @
• group must start with 'group:'
• tag must start with 'tag:'

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