{"record":{"id":"20a05624ece8f6d1","repo":"juanfont/headscale","slug":"unknown-autogroup","errorCode":null,"errorMessage":"unknown autogroup","messagePattern":"unknown autogroup","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hscontrol/policy/v2/types.go","lineNumber":117,"sourceCode":"// without the matching server-side machinery would be misleading — nodes\n// would advertise a feature that does not work. Reject at policy load and\n// point operators at the issue.\nvar nodeAttrUnsupportedCaps = map[tailcfg.NodeCapability]string{\n\ttailcfg.NodeAttrFunnel: \"https://github.com/juanfont/headscale/issues/2527\",\n}\n\n// Policy validation errors.\nvar (\n\tErrInvalidUsername             = errors.New(\"username must contain @\")\n\tErrUserNotFound                = errors.New(\"user not found\")\n\tErrMultipleUsersFound          = errors.New(\"multiple users found\")\n\tErrInvalidGroupFormat          = errors.New(\"group must start with 'group:'\")\n\tErrInvalidTagFormat            = errors.New(\"tag must start with 'tag:'\")\n\tErrInvalidHostname             = errors.New(\"invalid hostname\")\n\tErrHostResolve                 = errors.New(\"error resolving host\")\n\tErrInvalidPrefix               = errors.New(\"invalid prefix\")\n\tErrInvalidAutogroup            = errors.New(\"invalid autogroup\")\n\tErrUnknownAutogroup            = errors.New(\"unknown autogroup\")\n\tErrHostportMissingColon        = errors.New(\"hostport must contain a colon\")\n\tErrTypeNotSupported            = errors.New(\"type not supported\")\n\tErrInvalidAlias                = errors.New(\"invalid alias format\")\n\tErrInvalidAutoApprover         = errors.New(\"invalid auto approver format\")\n\tErrInvalidOwner                = errors.New(\"invalid owner format\")\n\tErrGroupNotDefined             = errors.New(\"group not defined in policy\")\n\tErrInvalidGroupMember          = errors.New(\"invalid group member type\")\n\tErrGroupValueNotArray          = errors.New(\"group value must be an array of users\")\n\tErrInvalidHostIP               = errors.New(\"hostname contains invalid IP address\")\n\tErrTagNotDefined               = errors.New(\"tag not found\")\n\tErrAutoApproverNotAlias        = errors.New(\"auto approver is not an alias\")\n\tErrInvalidACLAction            = errors.New(\"invalid ACL action\")\n\tErrInvalidSSHAction            = errors.New(\"invalid SSH action\")\n\tErrInvalidProtocolNumber       = errors.New(\"invalid protocol number\")\n\tErrProtocolLeadingZero         = errors.New(\"leading 0 not permitted in protocol number\")\n\tErrProtocolOutOfRange          = errors.New(\"protocol number out of range (0-255)\")\n\tErrAutogroupNotSupported       = errors.New(\"autogroup not supported in headscale\")\n\tErrAutogroupInternetSrc        = errors.New(\"autogroup:internet can only be used in ACL destinations\")","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/policy/v2/types.go#L99-L135","documentation":"AutoGroup.resolve (hscontrol/policy/v2/types.go:825-828) is reached when the token parses as an autogroup from the allowed grammar set but headscale has no resolver for it in the position/context being compiled — i.e. it is syntactically known but not supported for that resolution path. The offending value is included in the wrapped error.","triggerScenarios":"An autogroup that passes UnmarshalJSON but has no implementation in the resolving code path — typically newer autogroups accepted by the parser but not wired into headscale's resolver, or valid-in-one-position autogroups reaching an unsupported resolver. Fires at policy compile, distinct from the parse-time ErrInvalidAutogroup.","commonSituations":"headscale version skew: a policy written for a newer headscale that supports more autogroups; using an autogroup in a context (e.g. nodeAttrs, autoApprovers) where only a subset resolves.","solutions":["Check the error's included value and the headscale docs for where that autogroup is supported","Move the autogroup to a supported position (e.g. ACL dst for autogroup:internet)","Upgrade headscale if the autogroup is supported in a newer release"],"exampleFix":"// before\n{\"autoApprovers\": {\"routes\": {\"10.0.0.0/8\": [\"autogroup:danger-all\"]}}}\n// after\n{\"autoApprovers\": {\"routes\": {\"10.0.0.0/8\": [\"group:admins\"]}}}","handlingStrategy":"validation","validationCode":"// gate autogroup usage by position before compile\nif tok == \"autogroup:internet\" && position != \"aclDst\" {\n    return fmt.Errorf(\"%s not supported at %s\", tok, position)\n}","typeGuard":"null","tryCatchPattern":"if errors.Is(err, policy.ErrUnknownAutogroup) {\n    // move the autogroup to a supported position or upgrade headscale\n}","preventionTips":["Check the docs for per-position autogroup support","Pin policy grammar to your headscale version"],"tags":["headscale","policy","autogroup","version-skew","validation"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}