hashicorp/nomad · error

bootstrap check failed: %v

Error message

bootstrap check failed: %v

What it means

UpsertACLTokens (bootstrap path) returns this when the read of the 'acl_token_bootstrap' index entry fails inside the write transaction. It means the check 'has bootstrap already been done?' could not be evaluated, not that bootstrap is blocked.

Source

Thrown at nomad/state/state_store.go:6584

	// No entry, we haven't bootstrapped yet
	if out == nil {
		return true, 0, nil
	}

	// 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)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the underlying error captured in %v (disk, BoltDB, memdb)
2. Retry the bootstrap command once storage is healthy
3. Restore server data from a snapshot and retry
4. Verify the index table integrity via operator debug tooling

// before bootstrapping, verify no ACLs exist
list, err := client.ACL().TokensList(nil)
if err == nil && len(list) > 0 { return fmt.Errorf("ACLs already present; bootstrap likely done") }

func isBootstrapCheckErr(err error) bool { return strings.HasPrefix(err.Error(), "bootstrap check failed") }

_, _, err := client.ACL().Bootstrap(nil)
if err != nil && strings.HasPrefix(err.Error(), "bootstrap check failed") {
    // transient state store error — retry with backoff
    time.Sleep(2 * time.Second)
    return retry()
}

When it happens

Trigger: Calling `nomad acl bootstrap` (or the ACL bootstrap API) when txn.First("index","id","acl_token_bootstrap") returns a memdb error — degraded/corrupt state store.

Common situations: First bootstrap after cluster init on a server with storage issues; snapshot restore leaving inconsistent index table.

Related errors

• ACL policy not found
• ACL role not found
• detected corrupted token within the state store: missing rol
• policy lookup failed: %v
• upserting policy failed: %v

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