hashicorp/nomad · error

Invalid reset index for ACL bootstrap

Error message

Invalid reset index for ACL bootstrap

What it means

When re-bootstrapping (reset), the provided resetIndex must exactly equal the stored acl_token_bootstrap index value. This error means the caller supplied a reset index that doesn't match the recorded one.

Source

Thrown at nomad/state/state_store.go:6590

	// Return the reset index if we've already bootstrapped
	return false, out.(*IndexEntry).Value, nil
}

// BootstrapACLTokens is used to create an initial ACL token.
func (s *StateStore) BootstrapACLTokens(msgType structs.MessageType, index uint64, resetIndex uint64, token *structs.ACLToken) error {
	txn := s.db.WriteTxnMsgT(msgType, index)
	defer txn.Abort()

	// Check if we have already done a bootstrap
	existing, err := txn.First("index", "id", "acl_token_bootstrap")
	if err != nil {
		return fmt.Errorf("bootstrap check failed: %v", err)
	}
	if existing != nil {
		if resetIndex == 0 {
			return fmt.Errorf("ACL bootstrap already done")
		} else if resetIndex != existing.(*IndexEntry).Value {
			return fmt.Errorf("Invalid reset index for ACL bootstrap")
		}
	}

	// Update the Create/Modify time
	token.CreateIndex = index
	token.ModifyIndex = index

	// Insert the token
	if err := txn.Insert("acl_token", token); err != nil {
		return fmt.Errorf("upserting token failed: %v", err)
	}

	// Update the indexes table, prevents future bootstrap until reset
	if err := txn.Insert("index", &IndexEntry{"acl_token", index}); err != nil {
		return fmt.Errorf("index update failed: %v", err)
	}
	if err := txn.Insert("index", &IndexEntry{"acl_token_bootstrap", index}); err != nil {
		return fmt.Errorf("index update failed: %v", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Confirm the correct reset index from your snapshot/backup metadata and retry with the exact value
2. Check the stored entry via operator endpoints/logs to see the expected value
3. Ensure you're targeting the intended cluster (wrong context/region)
4. If bootstrap was never legitimately done, inspect whether a stale acl_token_bootstrap entry should be cleaned via support procedure

Example fix

// before
nomad acl bootstrap -reset=9
// after
nomad acl bootstrap -reset=14  // matches stored index value

if resetIndex <= 0 { return fmt.Errorf("a positive -reset index from your backup metadata is required") }

func isValidResetIndex(i int) bool { return i > 0 }

token, _, err := client.ACL().BootstrapReset(resetIndex, nil)
if err != nil && strings.Contains(err.Error(), "Invalid reset index") {
    return fmt.Errorf("reset index %d does not match this cluster's recorded bootstrap index; verify backup metadata", resetIndex)
}

When it happens

Trigger: Calling `nomad acl bootstrap -reset=N` where N differs from the stored IndexEntry.Value; stale reset index from an older backup or another cluster.

Common situations: Using a reset index copied from the wrong cluster or an outdated snapshot; typo in the reset number; cluster was re-bootstrapped previously so the expected index changed.

Related errors

• bootstrap check failed: %v
• ACL bootstrap already done
• ACL policy not found
• ACL role not found
• detected corrupted token within the state store: missing rol

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