juanfont/headscale · error

validating policy user references

Error message

validating policy user references: %w

What it means

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

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.

Appendix: 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)