What causes "schema: verify fresh-bootstrap working set: %w" in gastownhall/beads?

Inspect the wrapped driver error and fix the underlying cause (connectivity, server type).

schema: verify fresh-bootstrap working set: %w

Error message

schema: verify fresh-bootstrap working set: %w

What it means

Counting rows in dolt_status (the working-set dirtiness check) failed at the driver level. The library cannot confirm the fresh database has a clean working set, so it fails closed and issues no heal capability.

Source

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

	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
// captured immediately after this logical open's exact CREATE DATABASE, and
// endpoint must identify the connection pool used for migration. Before any
// DOLT_RESET, MigrateUpWithLock revalidates the capability against the pinned,

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the wrapped driver error and fix the underlying cause (connectivity, server type).
Confirm the target is a Dolt sql-server exposing dolt_status.
Retry the full create-database + capture sequence.
Avoid reusing a pinned conn after an error; get a fresh pinned connection.

Example fix

// before
_ = conn // reused stale conn after earlier failure
// after
conn, err := pool.Conn(ctx)
if err != nil { return err }
cap, err := schema.CaptureFreshBootstrapHealCapability(ctx, conn, endpoint, db)

Defensive patterns

Strategy: retry

Validate before calling

if err := conn.PingContext(ctx); err != nil { return fmt.Errorf("connection unusable: %w", err) }

Try / catch

cap, err := schema.CaptureFreshBootstrapHealCapability(ctx, conn, endpoint, db)
if err != nil && strings.Contains(err.Error(), "verify fresh-bootstrap working set") {
    // transient; retry create+capture after reconnect
}

Prevention

Ping/reconnect before capture.
Use a context with adequate timeout during server startup.
Keep the target on a Dolt sql-server so dolt_status exists.
Get a new pinned connection after any prior error on the session.

When it happens

Trigger: SELECT COUNT(*) FROM dolt_status errors due to connection loss, context cancellation, a non-Dolt backend without dolt_status, or a poisoned pinned session.

Common situations: Same as other system-table failures: wrong server type, transient network drop during bootstrap, server restart mid-capture.

Related errors

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