{"record":{"id":"c4691a5b37971d6f","repo":"hashicorp/nomad","slug":"invalid-reset-index-for-acl-bootstrap","errorCode":null,"errorMessage":"Invalid reset index for ACL bootstrap","messagePattern":"Invalid reset index for ACL bootstrap","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/state/state_store.go","lineNumber":6590,"sourceCode":"\t// Return the reset index if we've already bootstrapped\n\treturn false, out.(*IndexEntry).Value, nil\n}\n\n// BootstrapACLTokens is used to create an initial ACL token.\nfunc (s *StateStore) BootstrapACLTokens(msgType structs.MessageType, index uint64, resetIndex uint64, token *structs.ACLToken) error {\n\ttxn := s.db.WriteTxnMsgT(msgType, index)\n\tdefer txn.Abort()\n\n\t// Check if we have already done a bootstrap\n\texisting, err := txn.First(\"index\", \"id\", \"acl_token_bootstrap\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"bootstrap check failed: %v\", err)\n\t}\n\tif existing != nil {\n\t\tif resetIndex == 0 {\n\t\t\treturn fmt.Errorf(\"ACL bootstrap already done\")\n\t\t} else if resetIndex != existing.(*IndexEntry).Value {\n\t\t\treturn fmt.Errorf(\"Invalid reset index for ACL bootstrap\")\n\t\t}\n\t}\n\n\t// Update the Create/Modify time\n\ttoken.CreateIndex = index\n\ttoken.ModifyIndex = index\n\n\t// Insert the token\n\tif err := txn.Insert(\"acl_token\", token); err != nil {\n\t\treturn fmt.Errorf(\"upserting token failed: %v\", err)\n\t}\n\n\t// Update the indexes table, prevents future bootstrap until reset\n\tif err := txn.Insert(\"index\", &IndexEntry{\"acl_token\", index}); err != nil {\n\t\treturn fmt.Errorf(\"index update failed: %v\", err)\n\t}\n\tif err := txn.Insert(\"index\", &IndexEntry{\"acl_token_bootstrap\", index}); err != nil {\n\t\treturn fmt.Errorf(\"index update failed: %v\", err)","sourceCodeStart":6572,"sourceCodeEnd":6608,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/state/state_store.go#L6572-L6608","documentation":"When re-bootstrapping (reset), the provided resetIndex must exactly equal the stored acl_token_bootstrap index value. This error means the caller supplied a reset index that doesn't match the recorded one.","triggerScenarios":"Calling `nomad acl bootstrap -reset=N` where N differs from the stored IndexEntry.Value; stale reset index from an older backup or another cluster.","commonSituations":"Using a reset index copied from the wrong cluster or an outdated snapshot; typo in the reset number; cluster was re-bootstrapped previously so the expected index changed.","solutions":["Confirm the correct reset index from your snapshot/backup metadata and retry with the exact value","Check the stored entry via operator endpoints/logs to see the expected value","Ensure you're targeting the intended cluster (wrong context/region)","If bootstrap was never legitimately done, inspect whether a stale acl_token_bootstrap entry should be cleaned via support procedure"],"exampleFix":"// before\nnomad acl bootstrap -reset=9\n// after\nnomad acl bootstrap -reset=14  // matches stored index value","handlingStrategy":"validation","validationCode":"if resetIndex <= 0 { return fmt.Errorf(\"a positive -reset index from your backup metadata is required\") }","typeGuard":"func isValidResetIndex(i int) bool { return i > 0 }","tryCatchPattern":"token, _, err := client.ACL().BootstrapReset(resetIndex, nil)\nif err != nil && strings.Contains(err.Error(), \"Invalid reset index\") {\n    return fmt.Errorf(\"reset index %d does not match this cluster's recorded bootstrap index; verify backup metadata\", resetIndex)\n}","preventionTips":["Record the bootstrap index value alongside your backup/snapshot metadata","Verify cluster identity (name/region) before applying a reset index","Keep one source of truth for bootstrap metadata per cluster"],"tags":["nomad","acl","bootstrap"],"backgroundTag":"acl-bootstrap-reset-index-mismatch","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}