hashicorp/nomad · error

bootstrap check failed

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.

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
Defensive patterns

Strategy: retry

Validate before calling

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

Type guard

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

Try / catch

_, _, 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()
}

Prevention

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


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

Appendix: 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)