{"record":{"id":"52ba4fa1b8b302c7","repo":"hashicorp/nomad","slug":"acl-binding-rule-insert-failed-acl-auth-method-no","errorCode":null,"errorMessage":"ACL binding rule insert failed: ACL auth method not found","messagePattern":"ACL binding rule insert failed: ACL auth method not found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/state/state_store_acl_binding_rule.go","lineNumber":77,"sourceCode":"\n\t// Ensure the rule hash is not zero to provide defense in depth. This\n\t// should be done outside the state store, so we do not spend time here and\n\t// thus Raft, when it can be avoided.\n\tif len(rule.Hash) == 0 {\n\t\trule.SetHash()\n\t}\n\n\t// This validation also happens within the RPC handler, but Raft latency\n\t// could mean that by the time the state call is invoked, another Raft\n\t// update has the auth method detailed in binding rule. Therefore, check\n\t// again while in our write txn.\n\tif !allowMissingAuthMethod {\n\t\tmethod, err := s.GetACLAuthMethodByName(nil, rule.AuthMethod)\n\t\tif err != nil {\n\t\t\treturn false, fmt.Errorf(\"ACL auth method lookup failed: %v\", err)\n\t\t}\n\t\tif method == nil {\n\t\t\treturn false, fmt.Errorf(\"ACL binding rule insert failed: ACL auth method not found\")\n\t\t}\n\t}\n\n\t// This validation also happens within the RPC handler, but Raft latency\n\t// could mean that by the time the state call is invoked, another Raft\n\t// update has already written a method with the same name. We therefore\n\t// need to check we are not trying to create a rule with an existing ID.\n\texistingRaw, err := txn.First(TableACLBindingRules, indexID, rule.ID)\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"ACL binding rule lookup failed: %v\", err)\n\t}\n\n\tvar existing *structs.ACLBindingRule\n\tif existingRaw != nil {\n\t\texisting = existingRaw.(*structs.ACLBindingRule)\n\t}\n\n\t// Depending on whether this is an initial create, or an update, we need to","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/state/state_store_acl_binding_rule.go#L59-L95","documentation":"Returned by upsertACLBindingRuleTxn when the binding rule references an AuthMethod name that does not exist in the state store and allowMissingAuthMethod is false. This is a re-validation inside the write txn because Raft latency may have deleted the method after RPC-level validation.","triggerScenarios":"UpsertACLBindingRules submitted for a rule whose AuthMethod field names a method that was deleted (or never existed) by the time the Raft entry is applied.","commonSituations":"Deleting an auth method while rules referencing it are being created (e.g. via Terraform/CI racing); typo'd AuthMethod name in config; out-of-order Raft application after auth-method deletion.","solutions":["Create the referenced auth method first (nomad acl auth-method create), then upsert the binding rule.","Fix the rule's AuthMethod field to an existing method name.","Check for concurrent deletions in your automation and order operations (upsert method before rules)."],"exampleFix":"// before\nrule := &structs.ACLBindingRule{AuthMethod: \"oidc-typo\", ...}\n// after (ensure method exists first)\nmethod, _ := stateStore.GetACLAuthMethodByName(nil, \"oidc\")\nif method == nil { createAuthMethod(...) }\nrule.AuthMethod = method.Name","handlingStrategy":"validation","validationCode":"m, _ := client.ACLAuthMethods().Get(rule.AuthMethod)\nif m == nil { return fmt.Errorf(\"auth method %q not found; create it first\", rule.AuthMethod) }","typeGuard":null,"tryCatchPattern":"err := upsertRule(rule)\nif err != nil && strings.Contains(err.Error(), \"ACL auth method not found\") {\n    // recreate the auth method, then retry the rule upsert\n}","preventionTips":["Order ops: auth method first, rules second","Avoid deleting methods while rules reference them","Validate AuthMethod names in IaC before apply"],"tags":["nomad","acl","binding-rule","auth-method","raft"],"backgroundTag":"referenced-resource-not-found","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"}