juanfont/headscale · error

username must contain @

Error message

username must contain @

What it means

Username.Validate (hscontrol/policy/v2/types.go:341-347) requires every username token in a policy to contain an '@'. headscale uses '@' as the discriminator that a bare string is a user (vs group:/tag: prefixes). If the username is not naturally an email, a trailing '@' must be appended; resolveUser strips it again before matching Email/Name (types.go:395).

Source

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

	ErrNodeAttrsAutogroupNotAllowed = errors.New("nodeAttrs target does not support this autogroup")
	ErrNodeAttrUnsupported          = errors.New("nodeAttrs uses a feature headscale does not yet support")
	ErrNodeAttrIPPoolUnsupported    = errors.New("nodeAttrs ipPool requires the IP allocator (https://github.com/juanfont/headscale/issues/2912)")
	ErrNodeAttrTargetUnsupported    = errors.New("nodeAttrs target alias type is not supported")
)

// nodeAttrUnsupportedCaps lists caps that headscale parses but cannot act on
// today. Each entry maps to the tracking issue an operator can follow. The
// caps are accepted by Tailscale SaaS, but delivering them via headscale
// without the matching server-side machinery would be misleading — nodes
// would advertise a feature that does not work. Reject at policy load and
// point operators at the issue.
var nodeAttrUnsupportedCaps = map[tailcfg.NodeCapability]string{
	tailcfg.NodeAttrFunnel: "https://github.com/juanfont/headscale/issues/2527",
}

// Policy validation errors.
var (
	ErrInvalidUsername             = errors.New("username must contain @")
	ErrUserNotFound                = errors.New("user not found")
	ErrMultipleUsersFound          = errors.New("multiple users found")
	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")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Append '@' to bare usernames ("alice" -> "alice@")
2. Use the full email when the user was created via email
3. Check the actual user Name/Email with 'headscale users list' and use that exact value plus '@' if needed

Example fix

// before
{"groups": {"group:admins": ["alice"]}}
// after
{"groups": {"group:admins": ["alice@"]}}

func validPolicyUsername(s string) bool { return strings.Contains(s, "@") }

func isPolicyUsername(s string) bool { return strings.Contains(s, "@") }

if errors.Is(err, policy.ErrInvalidUsername) {
    // the wrapped value shows the token; append '@' if it is a bare name
}

When it happens

Trigger: Unmarshalling any policy alias position (group member, tagOwner, grant src/dst) with a string lacking '@', e.g. "alice" instead of "alice@" or "alice@example.com". Thrown at UnmarshalJSON time, so the whole policy parse fails.

Common situations: Using OIDC/username-based identity where names are not emails and forgetting the trailing '@'; writing 'group:admins' members as bare names; migrating from a v1 policy or Tailscale ACL that allowed bare usernames.

Related errors

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

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