hashicorp/nomad · error

default ACL auth method already exists: %v

Error message

default ACL auth method already exists: %v

What it means

When upserting an ACL auth method marked Default, the state store enforces that only one default method may exist per store: it queries GetDefaultACLAuthMethod and rejects the write if a different method is already default. The wrapped value is the name of the conflicting existing default method. Unlike the other errors here, this is a deliberate business-rule validation, not an internal failure.

Source

Thrown at nomad/state/state_store_acl_sso.go:73

// to update the index table.
func (s *StateStore) upsertACLAuthMethodTxn(index uint64, txn *txn, method *structs.ACLAuthMethod) (bool, error) {

	// Ensure the method 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(method.Hash) == 0 {
		method.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 already written a method with the same name or default
	// setting. We therefore need to check we are not trying to create a method
	// with an existing name or a duplicate default for the same type.
	if method.Default {
		existingMethodsDefaultMethod, _ := s.GetDefaultACLAuthMethod(nil)
		if existingMethodsDefaultMethod != nil && existingMethodsDefaultMethod.Name != method.Name {
			return false, fmt.Errorf(
				"default ACL auth method already exists: %v", existingMethodsDefaultMethod.Name,
			)
		}
	}
	existingRaw, err := txn.First(TableACLAuthMethods, indexID, method.Name)
	if err != nil {
		return false, fmt.Errorf("ACL auth method lookup failed: %v", err)
	}

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

	// Depending on whether this is an initial create, or an update, we need to
	// check and set certain parameters. The most important is to ensure any
	// create index is carried over.
	if existing != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run nomad acl auth-method list (or the API) to find the existing default method and decide which one should be default.
2. If the existing method should keep the flag, remove -default (Default=false) from your new/updated method and retry.
3. To switch the default, first update the existing method to Default=false, then upsert the new one with Default=true.
4. Fix your automation/config so only one method carries Default=true.

Example fix

// before (CLI)
nomad acl auth-method create -name=new-oidc -default -type=oidc ...
// after
nomad acl auth-method update -name=old-oidc -default=false
nomad acl auth-method create -name=new-oidc -default -type=oidc ...

current, err := state.GetDefaultACLAuthMethod(nil)
if err != nil {
    return err
}
if method.Default && current != nil && current.Name != method.Name {
    return fmt.Errorf("default auth method %q already exists; unset it first", current.Name)
}

func isDuplicateDefaultErr(err error) bool {
    return err != nil && strings.Contains(err.Error(), "default ACL auth method already exists")
}

if err := upsertAuthMethod(m); err != nil {
    if isDuplicateDefaultErr(err) {
        // clear Default on the new method or unset the existing default, then retry
        m.Default = false
        return upsertAuthMethod(m)
    }
    return err
}

When it happens

Trigger: UpsertACLAuthMethods / upsertACLAuthMethodTxn receives an ACLAuthMethod with Default=true whose Name differs from the currently-stored default method's name.

Common situations: Running nomad acl auth-method create/update with -default on a cluster that already has another default method; IaC (Terraform) applying two default auth methods; copy-pasting a config where the default flag was left set.

Related errors

• errMissingACLAuthMethodName
• token name too long
• client token missing policies or roles
• management token cannot be associated with policies or roles
• token type must be client or management

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