hashicorp/nomad · error

ACL binding rules lookup failed: %v

Error message

ACL binding rules lookup failed: %v

What it means

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.

Source

Thrown at nomad/state/state_store_acl_binding_rule.go:171

		return errors.New("ACL binding rule not found")
	}

	// Delete the existing entry from the table.
	if err := txn.Delete(TableACLBindingRules, existing); err != nil {
		return fmt.Errorf("ACL binding rule deletion failed: %v", err)
	}
	return nil
}

// GetACLBindingRules returns an iterator that contains all ACL binding rules
// stored within state.
func (s *StateStore) GetACLBindingRules(ws memdb.WatchSet) (memdb.ResultIterator, error) {
	txn := s.db.ReadTxn()

	// Walk the entire table to get all ACL binding rules.
	iter, err := txn.Get(TableACLBindingRules, indexID)
	if err != nil {
		return nil, fmt.Errorf("ACL binding rules lookup failed: %v", err)
	}
	ws.Add(iter.WatchCh())

	return iter, nil
}

// GetACLBindingRule returns a single ACL binding rule specified by the input
// ID. The binding rule object will be nil, if no matching entry was found; it
// is the responsibility of the caller to check for this.
func (s *StateStore) GetACLBindingRule(ws memdb.WatchSet, ruleID string) (*structs.ACLBindingRule, error) {
	txn := s.db.ReadTxn()

	// Perform the ACL binding rule lookup using the ID.
	watchCh, existing, err := txn.FirstWatch(TableACLBindingRules, indexID, ruleID)
	if err != nil {
		return nil, fmt.Errorf("ACL binding rule lookup failed: %v", err)
	}
	ws.Add(watchCh)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the wrapped cause; if it names a missing index/table, restart the Nomad server to rebuild in-memory memdb from Raft.
2. If corruption persists, restore from a verified snapshot (nomad snapshot save/restore).
3. Ensure client/server Nomad versions match the release that introduced ACL binding rules (Nomad 1.4+).
4. Retry the list request; read errors during failover are usually transient.

// no caller-side check can prevent this; ensure server readiness instead
if serverState := agent.Server().State(); serverState != structs.ConsulStatusPassing {
    return fmt.Errorf("server not ready for state store reads")
}

iter, err := state.GetACLBindingRules(ws)
if err != nil && strings.Contains(err.Error(), "lookup failed") {
    // transient during startup/failover; retry with backoff
    return retryableError(err)
}

When it happens

Trigger: Calling StateStore.GetACLBindingRules (used by diffACLBindingRules for blocking-query diffing and the ACL binding-rule list RPC) when txn.Get(TableACLBindingRules, indexID) errors.

Common situations: State store schema mismatch after a downgrade; corrupted memdb after restore; blocking-query watchers hitting a store whose table definitions changed mid-flight.

Related errors

• ACL auth method lookup failed: %v
• ACL policy not found
• ACL role not found
• detected corrupted token within the state store: missing rol
• launch lookup failed: %v

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