{"record":{"id":"8821d34c206726b7","repo":"hashicorp/nomad","slug":"acl-token-lookup-failed-v","errorCode":null,"errorMessage":"acl token lookup failed: %v","messagePattern":"acl token lookup failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/state/state_store.go","lineNumber":6443,"sourceCode":"\t\t}\n\t}\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\treturn txn.Commit()\n}\n\n// ACLTokenByAccessorID is used to lookup a token by accessor ID\nfunc (s *StateStore) ACLTokenByAccessorID(ws memdb.WatchSet, id string) (*structs.ACLToken, error) {\n\tif id == \"\" {\n\t\treturn nil, fmt.Errorf(\"acl token lookup failed: missing accessor id\")\n\t}\n\n\ttxn := s.db.ReadTxn()\n\n\twatchCh, existing, err := txn.FirstWatch(\"acl_token\", \"id\", id)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"acl token lookup failed: %v\", err)\n\t}\n\tws.Add(watchCh)\n\n\t// If the existing token is nil, this indicates it does not exist in state.\n\tif existing == nil {\n\t\treturn nil, nil\n\t}\n\n\t// Assert the token type which allows us to perform additional work on the\n\t// token that is needed before returning the call.\n\ttoken := existing.(*structs.ACLToken)\n\n\t// Handle potential staleness of ACL role links.\n\tif token, err = s.fixTokenRoleLinks(txn, token); err != nil {\n\t\treturn nil, err\n\t}\n\treturn token, nil\n}","sourceCodeStart":6425,"sourceCodeEnd":6461,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/state/state_store.go#L6425-L6461","documentation":"Wraps a memdb FirstWatch error in ACLTokenByAccessorID: reading the 'acl_token' table by the 'id' index failed. Note that a nil result means the token simply does not exist (no error); this error means the lookup itself failed mechanically.","triggerScenarios":"txn.FirstWatch on 'acl_token'/'id' failing due to schema mismatch (missing 'id' index), store torn down concurrently, or corrupted in-memory state.","commonSituations":"Version-skewed binaries reading state written by other versions; forks with changed acl_token indexes; test harnesses with a closed StateStore.","solutions":["Restart the Nomad server to rebuild in-memory tables from BoltDB.","Verify the acl_token 'id' index exists in the running schema version.","Inspect the wrapped %v cause; restore from a state snapshot if corruption is confirmed."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"func canLookupByAccessor(id string) bool {\n    return strings.TrimSpace(id) != \"\"\n}","typeGuard":"func tokenNotFound(token *structs.ACLToken, err error) bool {\n    return err == nil && token == nil\n}","tryCatchPattern":"token, err := store.ACLTokenByAccessorID(ws, id)\nif err != nil {\n    return fmt.Errorf(\"token lookup failed mechanically: %w\", err)\n}\nif token == nil {\n    return structs.ErrTokenNotFound\n}","preventionTips":["Distinguish nil result (token absent) from error (lookup failed)","Restart servers when memdb lookups error; these are not 'not found' cases","Keep state schema aligned with binary version","Log the wrapped cause for post-mortem schema debugging"],"tags":["nomad","state-store","memdb","acl"],"backgroundTag":"state-store-lookup-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"}