{"record":{"id":"abc93a08aecfe87b","repo":"hashicorp/nomad","slug":"acl-binding-rules-lookup-failed-v","errorCode":null,"errorMessage":"ACL binding rules lookup failed: %v","messagePattern":"ACL binding rules lookup failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/state/state_store_acl_binding_rule.go","lineNumber":171,"sourceCode":"\t\treturn errors.New(\"ACL binding rule not found\")\n\t}\n\n\t// Delete the existing entry from the table.\n\tif err := txn.Delete(TableACLBindingRules, existing); err != nil {\n\t\treturn fmt.Errorf(\"ACL binding rule deletion failed: %v\", err)\n\t}\n\treturn nil\n}\n\n// GetACLBindingRules returns an iterator that contains all ACL binding rules\n// stored within state.\nfunc (s *StateStore) GetACLBindingRules(ws memdb.WatchSet) (memdb.ResultIterator, error) {\n\ttxn := s.db.ReadTxn()\n\n\t// Walk the entire table to get all ACL binding rules.\n\titer, err := txn.Get(TableACLBindingRules, indexID)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"ACL binding rules lookup failed: %v\", err)\n\t}\n\tws.Add(iter.WatchCh())\n\n\treturn iter, nil\n}\n\n// GetACLBindingRule returns a single ACL binding rule specified by the input\n// ID. The binding rule object will be nil, if no matching entry was found; it\n// is the responsibility of the caller to check for this.\nfunc (s *StateStore) GetACLBindingRule(ws memdb.WatchSet, ruleID string) (*structs.ACLBindingRule, error) {\n\ttxn := s.db.ReadTxn()\n\n\t// Perform the ACL binding rule lookup using the ID.\n\twatchCh, existing, err := txn.FirstWatch(TableACLBindingRules, indexID, ruleID)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"ACL binding rule lookup failed: %v\", err)\n\t}\n\tws.Add(watchCh)","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/state/state_store_acl_binding_rule.go#L153-L189","documentation":"GetACLBindingRules reads the whole TableACLBindingRules table via txn.Get on the 'id' index and wraps any error the memdb read returns. The error reflects an inability to even create the table iterator, pointing at a missing or misdefined index in the state store schema rather than an empty result set.","triggerScenarios":"Calling StateStore.GetACLBindingRules (used by diffACLBindingRules for blocking-query diffing and the ACL binding-rule list RPC) when txn.Get(TableACLBindingRules, indexID) errors.","commonSituations":"State store schema mismatch after a downgrade; corrupted memdb after restore; blocking-query watchers hitting a store whose table definitions changed mid-flight.","solutions":["Check the wrapped cause; if it names a missing index/table, restart the Nomad server to rebuild in-memory memdb from Raft.","If corruption persists, restore from a verified snapshot (nomad snapshot save/restore).","Ensure client/server Nomad versions match the release that introduced ACL binding rules (Nomad 1.4+).","Retry the list request; read errors during failover are usually transient."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// no caller-side check can prevent this; ensure server readiness instead\nif serverState := agent.Server().State(); serverState != structs.ConsulStatusPassing {\n    return fmt.Errorf(\"server not ready for state store reads\")\n}","typeGuard":null,"tryCatchPattern":"iter, err := state.GetACLBindingRules(ws)\nif err != nil && strings.Contains(err.Error(), \"lookup failed\") {\n    // transient during startup/failover; retry with backoff\n    return retryableError(err)\n}","preventionTips":["Retry table reads with backoff during server startup and failover.","Restart servers to rebuild memdb from Raft if errors persist.","Restore from a verified snapshot on persistent corruption.","Pin all servers to a Nomad release supporting ACL binding rules (1.4+)."],"tags":["nomad","state-store","acl","lookup"],"backgroundTag":"state-store-transaction-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"}