{"record":{"id":"15dc47edd445b5ba","repo":"hashicorp/nomad","slug":"acl-binding-rule-insert-failed-v","errorCode":null,"errorMessage":"ACL binding rule insert failed: %v","messagePattern":"ACL binding rule insert failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/state/state_store_acl_binding_rule.go","lineNumber":117,"sourceCode":"\n\t\t// If the rule already exists, check whether the update contains any\n\t\t// difference. If it doesn't, we can avoid a state update as well as\n\t\t// updates to any blocking queries.\n\t\tif existing.Equal(rule) {\n\t\t\treturn false, nil\n\t\t}\n\n\t\trule.CreateIndex = existing.CreateIndex\n\t\trule.ModifyIndex = index\n\t\trule.CreateTime = existing.CreateTime\n\t} else {\n\t\trule.CreateIndex = index\n\t\trule.ModifyIndex = index\n\t}\n\n\t// Insert the auth method into the table.\n\tif err := txn.Insert(TableACLBindingRules, rule); err != nil {\n\t\treturn false, fmt.Errorf(\"ACL binding rule insert failed: %v\", err)\n\t}\n\treturn true, nil\n}\n\n// DeleteACLBindingRules is responsible for batch deleting ACL binding rules.\n// It uses a single write transaction for efficiency, however, any error means\n// no entries will be committed. An error is produced if a rule is not found\n// within state which has been passed within the array.\nfunc (s *StateStore) DeleteACLBindingRules(index uint64, bindingRuleIDs []string) error {\n\ttxn := s.db.WriteTxnMsgT(structs.ACLBindingRulesDeleteRequestType, index)\n\tdefer txn.Abort()\n\n\tfor _, ruleID := range bindingRuleIDs {\n\t\tif err := s.deleteACLBindingRuleTxn(txn, ruleID); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/state/state_store_acl_binding_rule.go#L99-L135","documentation":"Nomad's state store failed to insert an ACL binding rule row into the memdb table during a write transaction (txn.Insert on TableACLBindingRules returned an error). This wraps a low-level memdb error, which in practice almost always means a schema/table definition problem or a corrupted/invalid index rather than a caller-facing condition. It is surfaced from upsertACLBindingRuleTxn, which runs inside UpsertACLBindingRules and is also exercised by event-stream tests.","triggerScenarios":"Calling StateStore.UpsertACLBindingRules (via the ACL binding rule upsert RPC or Restore path) when the underlying memdb txn.Insert against TableACLBindingRules fails — e.g. the binding rule object violates the table's index schema (nil ID, malformed index tuple) or the memdb table definition is inconsistent.","commonSituations":"Corrupted state store files after an unclean shutdown or a failed restore; internal upgrades that change the ACL binding rule table schema; bugs in code constructing structs.ACLBindingRule with empty/invalid fields before upsert; tests injecting malformed rules via Test_eventsFromChanges_ACLBindingRule.","solutions":["Inspect the wrapped %v cause in the log to identify the underlying memdb error and fix the offending object (e.g. ensure the binding rule has a valid ID and AuthMethod).","If it appears after an unclean shutdown or restore, restore the state store from a snapshot (nomad snapshot inspect/save) or re-run with a rebuilt Raft state.","Verify Nomad version consistency across agents/clients; upgrade to a release with the ACL binding rule schema fixes if you recently upgraded.","If reproducible, file an issue with the wrapped error text — this path should never fail for well-formed inputs."],"exampleFix":"// before: rule constructed without ID\nrule := &structs.ACLBindingRule{AuthMethod: \"auth0\"}\n// after\nrule := &structs.ACLBindingRule{ID: uuid.Generate(), AuthMethod: \"auth0\"}","handlingStrategy":"try-catch","validationCode":"if rule == nil || rule.ID == \"\" || rule.AuthMethod == \"\" {\n    return fmt.Errorf(\"invalid ACL binding rule: missing ID or AuthMethod\")\n}","typeGuard":"func isValidBindingRule(r *structs.ACLBindingRule) bool {\n    return r != nil && r.ID != \"\" && r.AuthMethod != \"\"\n}","tryCatchPattern":"if err := stateStore.UpsertACLBindingRules(idx, rules); err != nil {\n    if strings.Contains(err.Error(), \"ACL binding rule insert failed\") {\n        // log wrapped cause, restore/rebuild state store before retrying\n        return fmt.Errorf(\"state store insert rejected: %w\", err)\n    }\n    return err\n}","preventionTips":["Always generate a valid UUID for ACLBindingRule.ID before upserting.","Snapshot the state store before upgrades or restores so corruption is recoverable.","Keep Nomad server versions homogeneous to avoid schema mismatches.","Alert on any occurrence — this wrap signals internal state store problems, not user errors."],"tags":["nomad","state-store","acl","memdb"],"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"}