juanfont/headscale · error

collecting relay target IPs: %w

Error message

collecting relay target IPs: %w

What it means

Error "collecting relay target IPs: %w" thrown in juanfont/headscale.

Source

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

		log.Warn().Err(testErr).Msg("policy sshTests failed at boot; server starting anyway, fix the policy and reload")
	}

	return &pm, nil
}

// updateLocked updates the filter rules based on the current policy and nodes.
// It must be called with the lock held.
func (pm *PolicyManager) updateLocked() (bool, error) {
	// Compile all grants once. Both global and per-node filter
	// rules are derived from these compiled grants.
	pm.compiledGrants = pm.pol.compileGrants(pm.users, pm.nodes)
	pm.userNodeIdx = buildUserNodeIndex(pm.nodes)
	pm.needsPerNodeFilter = hasPerNodeGrants(pm.compiledGrants)
	pm.viaTargetTags = collectViaTargetTags(pm.compiledGrants)

	relayTargetIPs, err := collectRelayTargetIPs(pm.compiledGrants)
	if err != nil {
		return false, fmt.Errorf("collecting relay target IPs: %w", err)
	}

	pm.relayTargetIPs = relayTargetIPs

	var filter []tailcfg.FilterRule
	if pm.pol == nil || (pm.pol.ACLs == nil && pm.pol.Grants == nil) {
		filter = tailcfg.FilterAllowAll
	} else {
		filter = globalFilterRules(pm.compiledGrants)
	}

	// Hash both the compiled filter AND the policy content together.
	// This ensures filterHash changes when policy changes, even for autogroup:self
	// where the compiled filter is always empty. This eliminates the need for
	// a separate policyHash field.
	filterHash := deephash.Hash(&filterAndPolicy{
		Filter: filter,
		Policy: pm.pol,

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (collecting relay target IPs); 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 (collecting relay target IPs); retry the operation after fixing the input, configuration, or environment.

When it happens

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

Common situations: Resolving relay target IPs from the policy failed. Check the policy's relay/destination entries are valid aliases, hosts, or prefixes.

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