juanfont/headscale · error

multiple users found

Error message

multiple users found

What it means

resolveUser (hscontrol/policy/v2/types.go:412-413) collects every user whose Email or Name equals the token (after stripping '@'); if more than one matches, the reference is ambiguous and policy compilation fails with this sentinel including the token and the matched users. hscontrol/policy/v2/policy.go:118 special-cases it during compile to surface it clearly.

Source

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

	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")
	ErrTagNotDefined               = errors.New("tag not found")
	ErrAutoApproverNotAlias        = errors.New("auto approver is not an alias")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Disambiguate by referencing the user's ProviderIdentifier (OIDC sub) instead of email/name
2. Delete or rename the duplicate user via 'headscale users' commands so only one matches
3. Put the ambiguous user in a group and reference group:name instead

Example fix

// before
{"acls": [{"action": "accept", "src": ["alice@example.com"], "dst": ["*"]}]}
// after (unique OIDC subject)
{"acls": [{"action": "accept", "src": ["294872317294"], "dst": ["*"]}]}

// detect ambiguous Email/Name duplicates before applying policy
tok := strings.TrimSuffix(token, "@")
matches := 0
for _, u := range users {
    if u.Email == tok || u.Name == tok { matches++ }
}
if matches > 1 { return fmt.Errorf("ambiguous user %q", token) }

null

if errors.Is(err, policy.ErrMultipleUsersFound) {
    // the message lists matched users; switch to ProviderIdentifier or dedupe
}

When it happens

Trigger: Two headscale users share the same Name or Email (e.g. a locally created 'alice' and an OIDC 'alice' with equal Name), and the policy references that bare name/email. ProviderIdentifier matches return early, so this only fires on Email/Name collisions.

Common situations: Migrating from local auth to OIDC leaves a duplicate user with the same email; renaming users created duplicates; multiple IdP accounts mapped to the same Name field.

Related errors

• user not found
• updating policy manager users: %w
• oidc state parameter is too short
• empty OIDC callback params
• extracting ID token

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