{"record":{"id":"6ddcc89adbe8204c","repo":"hashicorp/nomad","slug":"acl-policy-lookup-failed-v","errorCode":null,"errorMessage":"acl policy lookup failed: %v","messagePattern":"acl policy lookup failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/state/state_store.go","lineNumber":6308,"sourceCode":"\t// Delete the policy\n\tfor _, name := range names {\n\t\tif _, err := txn.DeleteAll(\"acl_policy\", \"id\", name); err != nil {\n\t\t\treturn fmt.Errorf(\"deleting acl policy failed: %v\", err)\n\t\t}\n\t}\n\tif err := txn.Insert(\"index\", &IndexEntry{\"acl_policy\", index}); err != nil {\n\t\treturn fmt.Errorf(\"index update failed: %v\", err)\n\t}\n\treturn txn.Commit()\n}\n\n// ACLPolicyByName is used to lookup a policy by name\nfunc (s *StateStore) ACLPolicyByName(ws memdb.WatchSet, name string) (*structs.ACLPolicy, error) {\n\ttxn := s.db.ReadTxn()\n\n\twatchCh, existing, err := txn.FirstWatch(\"acl_policy\", \"id\", name)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"acl policy lookup failed: %v\", err)\n\t}\n\tws.Add(watchCh)\n\n\tif existing != nil {\n\t\treturn existing.(*structs.ACLPolicy), nil\n\t}\n\treturn nil, nil\n}\n\n// ACLPolicyByNamePrefix is used to lookup policies by prefix\nfunc (s *StateStore) ACLPolicyByNamePrefix(ws memdb.WatchSet, prefix string) (memdb.ResultIterator, error) {\n\ttxn := s.db.ReadTxn()\n\n\titer, err := txn.Get(\"acl_policy\", \"id_prefix\", prefix)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"acl policy lookup failed: %v\", err)\n\t}\n\tws.Add(iter.WatchCh())","sourceCodeStart":6290,"sourceCodeEnd":6326,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/state/state_store.go#L6290-L6326","documentation":"Thrown by StateStore.ACLPolicyByName when the WatchFirst/FirstWatch lookup of an ACL policy by exact name fails in memdb. This is a read-path error: it wraps an internal query failure, not a missing policy (missing policies return nil, nil). Callers (ACL Get Policy RPC, token resolution) surface it as a 500-style internal error.","triggerScenarios":"ACL policy read by name (GET /v1/acl/policy/:name, nomad acl policy info) while the memdb FirstWatch query on acl_policy errors — internal store failure, corruption, or memory exhaustion; also hit indirectly when resolving policies attached to ACL tokens.","commonSituations":"Reading policies on a degraded/corrupted server; heavy blocking-query load exhausting memory; issues after partial snapshot restore.","solutions":["Retry the read request","Confirm the exact policy name with nomad acl policy list (though name mismatch yields 'not found', not this error)","Check server health/logs for memdb errors; restart the server if needed","Restore from snapshot if state corruption is indicated"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Distinguish 'not found' (safe) from internal failure using the read API\nconst policy = await nomad.get(`/v1/acl/policy/${encodeURIComponent(name)}`).catch(e => {\n  if (e.status === 404) return null; // policy absent is normal\n  throw e;                           // 500-class: internal lookup failure\n});","typeGuard":"function isNotFound(e) {\n  return e && (e.status === 404 || /not found/i.test(e.message || ''));\n}","tryCatchPattern":"try {\n  const policy = await nomad.get(`/v1/acl/policy/${encodeURIComponent(name)}`);\n} catch (e) {\n  if (isNotFound(e)) return null;\n  if (String(e).includes('acl policy lookup failed')) return retryWithBackoff(readPolicy, name);\n  throw e;\n}","preventionTips":["Treat 404 and 5xx differently: 404 is expected for absent policies","Retry reads with backoff on 500-class failures","Watch server memory on clusters with heavy blocking-query ACL traffic","Restore from snapshot if lookup failures persist across restarts"],"tags":["nomad","acl","state-store","read-path"],"backgroundTag":"acl-policy-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"}