{"record":{"id":"f42ae84f7435ae1c","repo":"juanfont/headscale","slug":"auth-key-has-already-been-used","errorCode":null,"errorMessage":"auth-key has already been used","messagePattern":"auth-key has already been used","errorType":"http","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"hscontrol/db/preauth_keys.go","lineNumber":23,"sourceCode":"\t\"fmt\"\n\t\"slices\"\n\t\"strings\"\n\t\"time\"\n\n\t\"github.com/juanfont/headscale/hscontrol/types\"\n\t\"golang.org/x/crypto/bcrypt\"\n\t\"gorm.io/gorm\"\n\t\"tailscale.com/util/rands\"\n\t\"tailscale.com/util/set\"\n)\n\nvar (\n\t// ErrPreAuthKeyNotFound wraps gorm.ErrRecordNotFound so an unknown or\n\t// deleted key is treated as a missing record by callers, which the\n\t// registration handler maps to a 401 rather than a raw server error.\n\tErrPreAuthKeyNotFound          = fmt.Errorf(\"auth-key not found: %w\", gorm.ErrRecordNotFound)\n\tErrPreAuthKeyExpired           = errors.New(\"auth-key expired\")\n\tErrSingleUseAuthKeyHasBeenUsed = errors.New(\"auth-key has already been used\")\n\tErrUserMismatch                = errors.New(\"user mismatch\")\n\tErrPreAuthKeyACLTagInvalid     = errors.New(\"auth-key tag is invalid\")\n)\n\n// validateACLTags deduplicates, sorts, and checks that every tag carries the\n// \"tag:\" prefix. Shared by the pre-auth-key and OAuth credential paths so both\n// enforce the same tag shape.\nfunc validateACLTags(tags []string) ([]string, error) {\n\ttags = set.SetOf(tags).Slice()\n\tslices.Sort(tags)\n\n\tfor _, tag := range tags {\n\t\tif !strings.HasPrefix(tag, \"tag:\") {\n\t\t\treturn nil, fmt.Errorf(\n\t\t\t\t\"%w: '%s' did not begin with 'tag:'\",\n\t\t\t\tErrPreAuthKeyACLTagInvalid,\n\t\t\t\ttag,\n\t\t\t)","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/db/preauth_keys.go#L5-L41","documentation":"Sentinel in hscontrol/db/preauth_keys.go returned by UsePreAuthKey when a key flagged single-use (--reusable=false, the default) is presented for registration a second time. The key row records its use; any subsequent attempt is rejected regardless of expiration.","triggerScenarios":"Baking one non-reusable auth-key into a VM/PXE template or docker image and booting multiple nodes from it; re-running `tailscale up --auth-key=...` after the first registration succeeded.","commonSituations":"Mass-provisioning with a single key; enrollment retries after a partially successful first attempt already consumed the key.","solutions":["Create a reusable key for templated provisioning: `headscale preauthkeys create --reusable`","Or generate one key per node from an orchestration step (via CLI or API) before first boot","For a failed first enrollment, mint a fresh key rather than retrying the consumed one"],"exampleFix":"# before\nheadscale preauthkeys create --user infra  # single-use default; cloned VMs fail\n\n# after\nheadscale preauthkeys create --user infra --reusable","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := db.UsePreAuthKey(tx, pak, user); err != nil {\n    if errors.Is(err, db.ErrSingleUseAuthKeyHasBeenUsed) {\n        return registrationFailed(401, \"single-use key already consumed; request a new key\")\n    }\n    return err\n}","preventionTips":["Use --reusable keys in golden images and templates","Generate one key per node from orchestration (CLI/API) instead of sharing keys","Treat a consumed-key error as a signal to mint a new key, never to retry"],"tags":["preauth-key","registration","single-use","headscale"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}