{"record":{"id":"71048f9a89c896da","repo":"juanfont/headscale","slug":"errinvalidallocationstrategy","errorCode":"ErrInvalidAllocationStrategy","errorMessage":"invalid prefix allocation strategy: %q, allowed options: %s, %s","messagePattern":"invalid prefix allocation strategy: %q, allowed options: (.+?), (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hscontrol/types/config.go","lineNumber":1168,"sourceCode":"\t\t\t\"ranges as described in the example configuration.\",\n\t\t\t\"\",\n\t\t\t\"Any issue raised using a range outside of the\",\n\t\t\t\"supported range will be labelled as wontfix\",\n\t\t\t\"and closed.\",\n\t\t})\n\t}\n\n\tallocStr := viper.GetString(\"prefixes.allocation\")\n\n\tvar alloc IPAllocationStrategy\n\n\tswitch allocStr {\n\tcase string(IPAllocationStrategySequential):\n\t\talloc = IPAllocationStrategySequential\n\tcase string(IPAllocationStrategyRandom):\n\t\talloc = IPAllocationStrategyRandom\n\tdefault:\n\t\treturn nil, fmt.Errorf(\n\t\t\t\"%w: %q, allowed options: %s, %s\",\n\t\t\tErrInvalidAllocationStrategy,\n\t\t\tallocStr,\n\t\t\tIPAllocationStrategySequential,\n\t\t\tIPAllocationStrategyRandom,\n\t\t)\n\t}\n\n\tdnsConfig, err := dns()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tderpConfig := derpConfig()\n\tlogTailConfig := logtailConfig()\n\n\toidcClientSecret := viper.GetString(\"oidc.client_secret\")\n","sourceCodeStart":1150,"sourceCodeEnd":1186,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/types/config.go#L1150-L1186","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set prefixes.allocation to exactly \"sequential\" or \"random\"","Remove the prefixes.allocation key to fall back to the built-in default","Check the config reference docs for the current accepted literals after upgrading headscale"],"exampleFix":"# before\nprefixes:\n  allocation: randomish\n# after\nprefixes:\n  allocation: random","handlingStrategy":"validation","validationCode":"var validAllocation = map[string]bool{\"sequential\": true, \"random\": true}\n\nif v := os.Getenv(\"PREFIX_ALLOCATION\"); v != \"\" && !validAllocation[v] {\n    return fmt.Errorf(\"prefixes.allocation must be sequential or random, got %q\", v)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin allocation values from an enum in templated configs rather than free text","Diff config files against the reference config after each headscale upgrade"],"tags":["config","ip-allocation","startup"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}