ACL binding rule insert failed: ACL auth method not found

Error message

ACL binding rule insert failed: ACL auth method not found

What it means

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.

Source

Thrown at nomad/state/state_store_acl_binding_rule.go:77

	// Ensure the rule hash is not zero to provide defense in depth. This
	// should be done outside the state store, so we do not spend time here and
	// thus Raft, when it can be avoided.
	if len(rule.Hash) == 0 {
		rule.SetHash()
	}

	// This validation also happens within the RPC handler, but Raft latency
	// could mean that by the time the state call is invoked, another Raft
	// update has the auth method detailed in binding rule. Therefore, check
	// again while in our write txn.
	if !allowMissingAuthMethod {
		method, err := s.GetACLAuthMethodByName(nil, rule.AuthMethod)
		if err != nil {
			return false, fmt.Errorf("ACL auth method lookup failed: %v", err)
		}
		if method == nil {
			return false, fmt.Errorf("ACL binding rule insert failed: ACL auth method not found")
		}
	}

	// This validation also happens within the RPC handler, but Raft latency
	// could mean that by the time the state call is invoked, another Raft
	// update has already written a method with the same name. We therefore
	// need to check we are not trying to create a rule with an existing ID.
	existingRaw, err := txn.First(TableACLBindingRules, indexID, rule.ID)
	if err != nil {
		return false, fmt.Errorf("ACL binding rule lookup failed: %v", err)
	}

	var existing *structs.ACLBindingRule
	if existingRaw != nil {
		existing = existingRaw.(*structs.ACLBindingRule)
	}

	// Depending on whether this is an initial create, or an update, we need to

View on GitHub (pinned to 482b49bf1a)

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).

Example fix

// before
rule := &structs.ACLBindingRule{AuthMethod: "oidc-typo", ...}
// after (ensure method exists first)
method, _ := stateStore.GetACLAuthMethodByName(nil, "oidc")
if method == nil { createAuthMethod(...) }
rule.AuthMethod = method.Name

Defensive patterns

Strategy: validation

Validate before calling

m, _ := client.ACLAuthMethods().Get(rule.AuthMethod)
if m == nil { return fmt.Errorf("auth method %q not found; create it first", rule.AuthMethod) }

Try / catch

err := upsertRule(rule)
if err != nil && strings.Contains(err.Error(), "ACL auth method not found") {
    // recreate the auth method, then retry the rule upsert
}

Prevention

Order ops: auth method first, rules second
Avoid deleting methods while rules reference them
Validate AuthMethod names in IaC before apply

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/52ba4fa1b8b302c7. Report an issue: GitHub.