juanfont/headscale · error

ErrInvalidAllocationStrategy

ErrInvalidAllocationStrategy

Error message

invalid prefix allocation strategy: %q, allowed options: %s, %s

What it means

Thrown when prefixes.allocation in the configuration is neither "sequential" nor "random". Headscale wraps ErrInvalidAllocationStrategy with the offending value and the two allowed options, because the IP allocation strategy drives how node addresses are assigned from the prefix pool and an unknown value cannot be safely defaulted.

Source

Thrown at hscontrol/types/config.go:1168

			"ranges as described in the example configuration.",
			"",
			"Any issue raised using a range outside of the",
			"supported range will be labelled as wontfix",
			"and closed.",
		})
	}

	allocStr := viper.GetString("prefixes.allocation")

	var alloc IPAllocationStrategy

	switch allocStr {
	case string(IPAllocationStrategySequential):
		alloc = IPAllocationStrategySequential
	case string(IPAllocationStrategyRandom):
		alloc = IPAllocationStrategyRandom
	default:
		return nil, fmt.Errorf(
			"%w: %q, allowed options: %s, %s",
			ErrInvalidAllocationStrategy,
			allocStr,
			IPAllocationStrategySequential,
			IPAllocationStrategyRandom,
		)
	}

	dnsConfig, err := dns()
	if err != nil {
		return nil, err
	}

	derpConfig := derpConfig()
	logTailConfig := logtailConfig()

	oidcClientSecret := viper.GetString("oidc.client_secret")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Set prefixes.allocation to exactly "sequential" or "random"
2. Remove the prefixes.allocation key to fall back to the built-in default
3. Check the config reference docs for the current accepted literals after upgrading headscale

Example fix

# before
prefixes:
  allocation: randomish
# after
prefixes:
  allocation: random

var validAllocation = map[string]bool{"sequential": true, "random": true}

if v := os.Getenv("PREFIX_ALLOCATION"); v != "" && !validAllocation[v] {
    return fmt.Errorf("prefixes.allocation must be sequential or random, got %q", v)
}

When it happens

Trigger: Setting prefixes.allocation: "randomly" (or any string other than the exact literals) in the config file and starting headscale. The switch in the prefix-configuration loader falls through to the default case.

Common situations: Typos, renamed values across headscale versions, or configs ported from documentation of a different fork. Older configs that predate the setting but contain a stale key with a wrong value.

Related errors

• no IPv4 or IPv6 prefix configured, minimum one prefix is req
• STUN address not set
• initial DERPMap is empty, Headscale requires at least one en
• database type not supported
• failed to allocate IP

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