{"record":{"id":"c752f3270e736b9d","repo":"juanfont/headscale","slug":"invalid-alias-w","errorCode":null,"errorMessage":"invalid alias: %w","messagePattern":"invalid alias: %w","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"hscontrol/policy/v2/test.go","lineNumber":325,"sourceCode":"\n\t\t\t\t*fail = append(*fail, dst)\n\t\t\t}\n\t\t}\n\t}\n\n\tcheck(test.Accept, true, &res.AcceptOK, &res.AcceptFail)\n\tcheck(test.Deny, false, &res.DenyOK, &res.DenyFail)\n\n\treturn res\n}\n\n// resolveTestSource resolves the Src alias of a [PolicyTest] into a slice of\n// [netip.Prefix]. [parseAlias] + [Alias.Resolve] cover every alias type the rest\n// of the policy engine supports, so tests inherit alias semantics for free.\nfunc resolveTestSource(src string, pol *Policy, users []types.User, nodes views.Slice[types.NodeView]) ([]netip.Prefix, error) {\n\talias, err := parseAlias(src)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"invalid alias: %w\", err)\n\t}\n\n\taddrs, err := alias.Resolve(pol, users, nodes)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"resolving: %w\", err)\n\t}\n\n\tif addrs == nil || addrs.Empty() {\n\t\treturn nil, nil\n\t}\n\n\treturn addrs.Prefixes(), nil\n}\n\n// evalReachability reports whether traffic from any srcPrefix to dst (in\n// `host:port` form) is allowed by filter for the requested protocol.\n//\n// Empty proto means the default set the client applies when proto is","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/policy/v2/test.go#L307-L343","documentation":"Thrown by the policy-test harness in hscontrol/policy/v2/test.go while resolving the 'Src' field of a PolicyTest. parseAlias rejected the source string, meaning it does not match any alias form the policy engine recognizes (user@, group:, tag:, autogroup:, host, CIDR/IP). The test cannot inherit alias semantics because the string is syntactically invalid before resolution even starts.","triggerScenarios":"A policy test block (the 'tests' section of a HuJSON/JSON policy) contains a Src value like 'userwithoutat', 'tag:', 'group', '10.0.0.0' (host bits set without a valid mask), or a typo such as 'autogroup:member '. resolveTestSource calls parseAlias(src) and it returns an error.","commonSituations":"Writing new policy tests by copying examples and forgetting the @ in a username, omitting the tag:/group: prefix, trailing whitespace, or using an IP without a prefix length. Also appears after upgrading headscale when alias grammar was tightened (e.g. stricter autogroup names).","solutions":["Check the Src string in the failing test entry against the alias forms: 'user@email', 'group:name', 'tag:name', 'autogroup:self|member|internet|tagged|danger-all', a hostname from the hosts section, or a valid CIDR like '10.0.0.1/32'.","If the source is a username, make sure it contains '@'; if a tag or group, make sure the prefix and a non-empty name are present.","Run the policy file through headscale's policy loader (or 'headscale policy check' / unit TestPolicy) to surface the exact parseAlias error wrapped behind 'invalid alias:'.","If you believe the string is valid, verify you are on a headscale version that supports that alias type (e.g. autogroup:danger-all was added later)."],"exampleFix":"// before (in policy tests block)\n\"tests\": [{\"src\": \"alice\", \"accept\": [\"web:80\"]}]\n\n// after\n\"tests\": [{\"src\": \"alice@example.com\", \"accept\": [\"web:80,443\"]}]","handlingStrategy":"validation","validationCode":"// Before adding a PolicyTest, confirm the Src parses as an alias.\nimport \"github.com/juanfont/headscale/hscontrol/policy/v2\"\n\nif _, err := v2.ParseAliasForTest(src); err != nil { // or expose parseAlias via a helper\n    return fmt.Errorf(\"test src %q is not a valid alias: %w\", src, err)\n}","typeGuard":null,"tryCatchPattern":"if err := runPolicyTests(pol, users, nodes); err != nil {\n    // err wraps 'invalid alias: <cause>'; surface cause, do not retry\n    log.Error().Err(err).Msg(\"policy test src invalid\")\n    return err\n}","preventionTips":["Keep a lint step that runs the policy test suite (headscale policy check / go test ./hscontrol/policy/...) in CI for every ACL change.","Copy Src formats from working entries: 'user@domain', 'group:x', 'tag:x', 'autogroup:self', '100.64.0.0/24'.","Never hand-type autogroup names; paste them from the version's docs."],"tags":["policy","acl","testing","configuration","go"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}