schema: verify fresh-bootstrap history: got %d commits, want

Error message

schema: verify fresh-bootstrap history: got %d commits, want 1

What it means

The fresh-bootstrap check requires exactly one commit (the initial Dolt init commit) in dolt_log. Any other count means the database is not pristine — either history already exists (migrations or writes ran) or the Dolt init didn't complete — so the library refuses to grant destructive DOLT_RESET authority.

Source

Thrown at internal/storage/schema/lock.go:134

	).Scan(&databaseName, &serverUUID, &initialHead); err != nil {
		return nil, fmt.Errorf("schema: capture fresh-bootstrap identity: %w", err)
	}
	if databaseName != expectedDatabase {
		return nil, fmt.Errorf("schema: capture fresh-bootstrap identity: database is %q, want %q", databaseName, expectedDatabase)
	}
	if serverUUID == "" {
		return nil, errors.New("schema: capture fresh-bootstrap identity: empty server UUID")
	}
	if initialHead == "" {
		return nil, errors.New("schema: capture fresh-bootstrap identity: empty initial HEAD")
	}

	var commitCount, dirtyCount int
	if err := conn.QueryRowContext(ctx, "SELECT COUNT(*) FROM dolt_log").Scan(&commitCount); err != nil {
		return nil, fmt.Errorf("schema: verify fresh-bootstrap history: %w", err)
	}
	if commitCount != 1 {
		return nil, fmt.Errorf("schema: verify fresh-bootstrap history: got %d commits, want 1", commitCount)
	}
	if err := conn.QueryRowContext(ctx, "SELECT COUNT(*) FROM dolt_status").Scan(&dirtyCount); err != nil {
		return nil, fmt.Errorf("schema: verify fresh-bootstrap working set: %w", err)
	}
	if dirtyCount != 0 {
		return nil, fmt.Errorf("schema: verify fresh-bootstrap working set: got %d dirty entries, want 0", dirtyCount)
	}

	return &FreshBootstrapHealCapability{
		endpoint:     endpoint,
		serverUUID:   serverUUID,
		databaseName: databaseName,
		initialHead:  initialHead,
	}, nil
}

// WithFreshBootstrapHeal enables the fresh-bootstrap self-heal for the #4566
// dirty-table guard (gastownhall/beads#5012). The capability must have been

View on GitHub (pinned to 71377f2769)

Solutions

Only capture immediately after a successful, fresh CREATE DATABASE of a truly new database.
Serialize database creation/migration with MigrateUpWithLock so no concurrent writer adds commits.
If commits already exist, the database is not fresh — skip heal and run normal migration; do not attempt to reset.
Check dolt_log contents to see what extra history was created and by whom.

Example fix

// before
cap, err := schema.CaptureFreshBootstrapHealCapability(ctx, conn, endpoint, db) // existing db: 12 commits
// after
if _, err := conn.ExecContext(ctx, "CREATE DATABASE IF NOT EXISTS `"+db+"`"); err == nil {
    cap, err = schema.CaptureFreshBootstrapHealCapability(ctx, conn, endpoint, db)
}

Defensive patterns

Strategy: validation

Validate before calling

var commits int
if err := conn.QueryRowContext(ctx, "SELECT COUNT(*) FROM dolt_log").Scan(&commits); err != nil { return err }
if commits > 1 { return fmt.Errorf("database not fresh: %d commits exist; skip heal path", commits) }

Try / catch

cap, err := schema.CaptureFreshBootstrapHealCapability(ctx, conn, endpoint, db)
if err != nil && strings.Contains(err.Error(), "commits, want 1") {
    // not a fresh database — proceed with normal migration, no reset
}

Prevention

Capture only immediately after a successful CREATE DATABASE of a brand-new database.
Serialize initialization across processes with the migration lock.
Never reuse a capture on a pre-existing database.
Audit dolt_log before assuming a database is fresh.

When it happens

Trigger: Calling CaptureFreshBootstrapHealCapability on a database that already existed (CREATE DATABASE was a no-op or raced with another process), after prior migrations ran, or on a database where Dolt init produced zero or multiple commits.

Common situations: Two processes racing to initialize the same database; re-running bootstrap against a long-lived database; a partially initialized Dolt database from a crashed prior run.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/4a59d2b222970fa0. Report an issue: GitHub.