juanfont/headscale · error

validating policy user references: %w

Error message

validating policy user references: %w

What it means

Error "validating policy user references: %w" thrown in juanfont/headscale.

Source

Thrown at hscontrol/policy/v2/policy.go:197

			checkAlias(dst)
		}
	}

	return multierr.New(errs...)
}

// NewPolicyManager creates a new [PolicyManager] from a policy file and a list of users and nodes.
// It returns an error if the policy file is invalid.
// The policy manager will update the filter rules based on the users and nodes.
func NewPolicyManager(b []byte, users []types.User, nodes views.Slice[types.NodeView]) (*PolicyManager, error) {
	policy, err := unmarshalPolicy(b)
	if err != nil {
		return nil, fmt.Errorf("parsing policy: %w", err)
	}

	err = validateUserReferences(policy, users)
	if err != nil {
		return nil, fmt.Errorf("validating policy user references: %w", err)
	}

	pm := PolicyManager{
		pol:                policy,
		users:              users,
		nodes:              nodes,
		sshPolicyMap:       xsync.NewMap[types.NodeID, *tailcfg.SSHPolicy](),
		filterRulesMap:     xsync.NewMap[types.NodeID, []tailcfg.FilterRule](),
		matchersForNodeMap: xsync.NewMap[types.NodeID, []matcher.Match](),
	}

	_, err = pm.updateLocked()
	if err != nil {
		return nil, err
	}

	// Boot path: log a warning if the stored policy's tests would
	// fail against the current users and nodes, but keep the server

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (validating policy user references); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (validating policy user references); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/policy/v2/policy.go:197 when the library encounters an invalid state.

Common situations: The policy references a user that does not exist in headscale. Create the referenced users first or fix the policy's user names.

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