What causes "%w: got %q, must be one of %v" in juanfont/headscale?

Use an autogroup exactly as listed in the error message, e.g. 'autogroup:member'.

%w: got %q, must be one of %v

Error message

%w: got %q, must be one of %v

What it means

AutoGroup.Validate rejected the token because it is not one of the known autogroups (autogroup:member, autogroup:tagged, autogroup:self, autogroup:internet, autogroup:nonroot, autogroup:danger-all). The error lists the accepted set; validation happens at policy unmarshal time.

Source

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

	AutoGroupSelf      AutoGroup = "autogroup:self"
	AutoGroupDangerAll AutoGroup = "autogroup:danger-all"
)

var autogroups = []AutoGroup{
	AutoGroupInternet,
	AutoGroupMember,
	AutoGroupNonRoot,
	AutoGroupTagged,
	AutoGroupSelf,
	AutoGroupDangerAll,
}

func (ag *AutoGroup) Validate() error {
	if slices.Contains(autogroups, *ag) {
		return nil
	}

	return fmt.Errorf("%w: got %q, must be one of %v", ErrInvalidAutogroup, *ag, autogroups)
}

func (ag *AutoGroup) UnmarshalJSON(b []byte) error {
	*ag = AutoGroup(strings.Trim(string(b), `"`))

	err := ag.Validate()
	if err != nil {
		return err
	}

	return nil
}

func (ag *AutoGroup) String() string {
	return string(*ag)
}

// MarshalJSON marshals the AutoGroup to JSON.

View on GitHub (pinned to 565fd254d0)

Solutions

Use an autogroup exactly as listed in the error message, e.g. 'autogroup:member'.
Check for trailing whitespace or quotes in the HuJSON value.
If you need 'autogroup:danger-all' or similar, upgrade headscale to a version that includes it.
If no autogroup fits, express the intent with groups/tags/CIDRs.

Example fix

// before
"src": ["autogroup:members"]

// after
"src": ["autogroup:member"]

Defensive patterns

Strategy: validation

Validate before calling

var knownAutogroups = []string{"autogroup:member", "autogroup:tagged", "autogroup:self", "autogroup:internet", "autogroup:nonroot", "autogroup:danger-all"}
func validAutogroup(s string) bool { return slices.Contains(knownAutogroups, s) }

Try / catch

if err := ag.Validate(); err != nil {
    if errors.Is(err, v2.ErrInvalidAutogroup) {
        // error message lists all valid names; pick one exactly
    }
    return err
}

Prevention

Copy autogroup names from the error message itself — it enumerates valid values.
Pin policy docs to the deployed headscale version.
Add a CI vocabulary check for autogroup tokens.

When it happens

Trigger: Values like 'autogroup:members' (plural), 'autogroup:admin', or 'autogroup:self ' (trailing space). slices.Contains(autogroups, ag) is false in AutoGroup.Validate.

Common situations: Typos and pluralization from memory; copying autogroup names from other systems' docs; headscale version differences where newer autogroups are unknown to older validators.

Related errors

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