hashicorp/nomad · error

ACL role lookup failed

Error message

ACL role lookup failed: %v

What it means

The memdb read of an ACL role failed inside upsertACLRoleTxn (e.g. the name-index uniqueness check); the wrapped lookup error aborts the role upsert rather than indicating a validation failure.

Solutions

  1. Retry the role upsert
  2. Inspect server logs for state store read errors
  3. Check for concurrent role writes racing the lookup
Defensive patterns

Strategy: retry

When it happens

Trigger: Thrown at nomad/state/state_store_acl.go:110 when the library encounters an invalid state.

Common situations: See trigger scenarios.


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

Appendix: source

Thrown at nomad/state/state_store_acl.go:110

	}

	// 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 deleted policies detailed in role. Therefore, check again
	// while in our write txn.
	if !allowMissingPolicies {
		if err := s.validateACLRolePolicyLinksTxn(txn, role); err != nil {
			return false, err
		}
	}

	// 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 role with the same name. We therefore need
	// to check we are not trying to create a role with an existing name.
	existingRaw, err := txn.First(TableACLRoles, indexName, role.Name)
	if err != nil {
		return false, fmt.Errorf("ACL role lookup failed: %v", err)
	}

	// Track our type asserted role, so we only need to do this once.
	var existing *structs.ACLRole

	// If we did not find an ACL Role within state with the same name, we need
	// to check using the ID index as the operator might be performing an
	// update on the role name.
	//
	// If we found an entry using the name index, we need to check that the ID
	// matches the object within the request.
	if existingRaw == nil {
		existingRaw, err = txn.First(TableACLRoles, indexID, role.ID)
		if err != nil {
			return false, fmt.Errorf("ACL role lookup failed: %v", err)
		}
		if existingRaw != nil {
			existing = existingRaw.(*structs.ACLRole)

View on GitHub (pinned to 482b49bf1a)