hashicorp/nomad · error

acl token lookup failed: %v

Error message

acl token lookup failed: %v

What it means

Wraps a memdb FirstWatch error in ACLTokenByAccessorID: reading the 'acl_token' table by the 'id' index failed. Note that a nil result means the token simply does not exist (no error); this error means the lookup itself failed mechanically.

Source

Thrown at nomad/state/state_store.go:6443

		}
	}
	if err := txn.Insert("index", &IndexEntry{"acl_token", index}); err != nil {
		return fmt.Errorf("index update failed: %v", err)
	}
	return txn.Commit()
}

// ACLTokenByAccessorID is used to lookup a token by accessor ID
func (s *StateStore) ACLTokenByAccessorID(ws memdb.WatchSet, id string) (*structs.ACLToken, error) {
	if id == "" {
		return nil, fmt.Errorf("acl token lookup failed: missing accessor id")
	}

	txn := s.db.ReadTxn()

	watchCh, existing, err := txn.FirstWatch("acl_token", "id", id)
	if err != nil {
		return nil, fmt.Errorf("acl token lookup failed: %v", err)
	}
	ws.Add(watchCh)

	// If the existing token is nil, this indicates it does not exist in state.
	if existing == nil {
		return nil, nil
	}

	// Assert the token type which allows us to perform additional work on the
	// token that is needed before returning the call.
	token := existing.(*structs.ACLToken)

	// Handle potential staleness of ACL role links.
	if token, err = s.fixTokenRoleLinks(txn, token); err != nil {
		return nil, err
	}
	return token, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Restart the Nomad server to rebuild in-memory tables from BoltDB.
2. Verify the acl_token 'id' index exists in the running schema version.
3. Inspect the wrapped %v cause; restore from a state snapshot if corruption is confirmed.

func canLookupByAccessor(id string) bool {
    return strings.TrimSpace(id) != ""
}

func tokenNotFound(token *structs.ACLToken, err error) bool {
    return err == nil && token == nil
}

token, err := store.ACLTokenByAccessorID(ws, id)
if err != nil {
    return fmt.Errorf("token lookup failed mechanically: %w", err)
}
if token == nil {
    return structs.ErrTokenNotFound
}

When it happens

Trigger: txn.FirstWatch on 'acl_token'/'id' failing due to schema mismatch (missing 'id' index), store torn down concurrently, or corrupted in-memory state.

Common situations: Version-skewed binaries reading state written by other versions; forks with changed acl_token indexes; test harnesses with a closed StateStore.

Related errors

• policy lookup failed: %v
• upserting policy failed: %v
• token lookup failed: %v
• ACL role insert failed: %v
• ACL policy lookup failed: %v

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