gastownhall/beads · error

schema: verify fresh-bootstrap history: %w

Error message

schema: verify fresh-bootstrap history: %w

What it means

The library verifies a freshly created database is pristine by counting rows in dolt_log. This error wraps a driver failure of that COUNT query — the history check could not even run, so no heal capability is issued (fail closed).

Source

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

	var databaseName, serverUUID, initialHead string
	if err := conn.QueryRowContext(ctx,
		"SELECT DATABASE(), @@server_uuid, DOLT_HASHOF('HEAD')",
	).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
}

View on GitHub (pinned to 71377f2769)

Solutions

  1. Read the wrapped error; if it says the table doesn't exist, confirm the target is a Dolt database, not plain MySQL.
  2. Reconnect and retry the bootstrap; the capability intentionally isn't granted on uncertainty.
  3. Ensure the pinned conn has no undrained result sets from prior CALL/SELECT statements.
  4. Give the context a generous timeout when the server is starting.

Example fix

// before
conn, _ := mysqlPool.Conn(ctx) // plain MySQL: no dolt_log
// after
conn, _ := doltServerPool.Conn(ctx) // Dolt sql-server endpoint
Defensive patterns

Strategy: validation

Validate before calling

var one int
if err := conn.QueryRowContext(ctx, "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = 'dolt_log'").Scan(&one); err != nil || one != 1 {
    return errors.New("target is not a Dolt database (dolt_log missing)")
}

Try / catch

cap, err := schema.CaptureFreshBootstrapHealCapability(ctx, conn, endpoint, db)
if err != nil && strings.Contains(err.Error(), "verify fresh-bootstrap history") {
    // driver-level failure; check server type / connectivity, retry
}

Prevention

When it happens

Trigger: SELECT COUNT(*) FROM dolt_log errors because the session lost connectivity, the context expired, the database is not Dolt-initialized (no dolt_log table), or the pinned connection was poisoned by an earlier undrained result set.

Common situations: Pointing beads at a plain MySQL database that has no dolt_log system table; a Dolt database whose Dolt branch/init was wiped; ctx cancellation during slow server startup.

Related errors

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