What causes "ACL auth method not found" in hashicorp/nomad?

Verify the method name with nomad acl auth-method list.

ACL auth method not found

Error message

ACL auth method not found

What it means

deleteACLAuthMethodTxn looks up an ACL auth method by name in the acl_auth_methods table before deletion. If no record matches, it returns "ACL auth method not found", aborting the delete so callers get an explicit error instead of a silent no-op. It backs the DeleteACLAuthMethods bulk path and the ACLAuthMethod.Delete RPC.

Source

Thrown at nomad/state/state_store_acl_sso.go:146

	// Update the index table to indicate an update has occurred.
	if err := txn.Insert(tableIndex, &IndexEntry{TableACLAuthMethods, index}); err != nil {
		return fmt.Errorf("index update failed: %v", err)
	}

	return txn.Commit()
}

// deleteACLAuthMethodTxn deletes a single ACL method name from the state store
// using the provided write transaction. It is the responsibility of the caller
// to update the index table.
func (s *StateStore) deleteACLAuthMethodTxn(txn *txn, methodName string) error {
	existing, err := txn.First(TableACLAuthMethods, indexID, methodName)
	if err != nil {
		return fmt.Errorf("ACL auth method lookup failed: %v", err)
	}
	if existing == nil {
		return errors.New("ACL auth method not found")
	}

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

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

	// Walk the entire table to get all ACL auth methods.
	iter, err := txn.Get(TableACLAuthMethods, indexID)
	if err != nil {
		return nil, fmt.Errorf("ACL auth method lookup failed: %v", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

Verify the method name with nomad acl auth-method list.
Handle the error as success if your desired state is 'method removed'.
Ensure the delete targets the same cluster where the auth method was created.

Example fix

// before
client.ACLAuthMethods().Delete("oidc", nil)
// after: tolerate already-deleted
if err := client.ACLAuthMethods().Delete("oidc", nil); err != nil && !strings.Contains(err.Error(), "not found") {
    return err
}

Defensive patterns

Strategy: try-catch

Validate before calling

_, _, err := client.ACLAuthMethods().Get(methodName, nil)
if err != nil {
    return nil // method already removed
}

Try / catch

err := client.ACLAuthMethods().Delete(methodName, nil)
if err != nil && strings.Contains(err.Error(), "ACL auth method not found") {
    return nil // already deleted
}

Prevention

Auth methods are name-keyed: keep names in a single source of truth for IaC.
Run `nomad acl auth-method list` before manual deletes.
Environment-separate configs to avoid cross-env name mistakes.

When it happens

Trigger: ACLAuthMethod.Delete RPC (nomad acl auth-method delete <name>) with a method name that is not in the state store; duplicate concurrent deletes; deleting on the wrong cluster/region.

Common situations: Terraform or scripts tearing down SSO config that was already removed; name typo (auth methods are keyed by name, not UUID); environment drift between staging and production.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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