{"record":{"id":"7e717777ee612bf4","repo":"hashicorp/nomad","slug":"bootstrap-check-failed-v","errorCode":null,"errorMessage":"bootstrap check failed: %v","messagePattern":"bootstrap check failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/state/state_store.go","lineNumber":6584,"sourceCode":"\n\t// No entry, we haven't bootstrapped yet\n\tif out == nil {\n\t\treturn true, 0, nil\n\t}\n\n\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","sourceCodeStart":6566,"sourceCodeEnd":6602,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/state/state_store.go#L6566-L6602","documentation":"UpsertACLTokens (bootstrap path) returns this when the read of the 'acl_token_bootstrap' index entry fails inside the write transaction. It means the check 'has bootstrap already been done?' could not be evaluated, not that bootstrap is blocked.","triggerScenarios":"Calling `nomad acl bootstrap` (or the ACL bootstrap API) when txn.First(\"index\",\"id\",\"acl_token_bootstrap\") returns a memdb error — degraded/corrupt state store.","commonSituations":"First bootstrap after cluster init on a server with storage issues; snapshot restore leaving inconsistent index table.","solutions":["Fix the underlying error captured in %v (disk, BoltDB, memdb)","Retry the bootstrap command once storage is healthy","Restore server data from a snapshot and retry","Verify the index table integrity via operator debug tooling"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// before bootstrapping, verify no ACLs exist\nlist, err := client.ACL().TokensList(nil)\nif err == nil && len(list) > 0 { return fmt.Errorf(\"ACLs already present; bootstrap likely done\") }","typeGuard":"func isBootstrapCheckErr(err error) bool { return strings.HasPrefix(err.Error(), \"bootstrap check failed\") }","tryCatchPattern":"_, _, err := client.ACL().Bootstrap(nil)\nif err != nil && strings.HasPrefix(err.Error(), \"bootstrap check failed\") {\n    // transient state store error — retry with backoff\n    time.Sleep(2 * time.Second)\n    return retry()\n}","preventionTips":["Run bootstrap once during cluster init and store the token in a secret manager","Check storage health if this error appears on a fresh cluster","Retry with backoff only for transient underlying errors"],"tags":["nomad","acl","bootstrap","state-store"],"backgroundTag":"acl-bootstrap-failed","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"}