gastownhall/beads · critical

failed to initialize schema: %w

Error message

failed to initialize schema: %w

What it means

This error wraps a failure from store.initSchema during DoltStore open. It means schema migrations (DDL) could not be applied, so the store cannot guarantee the expected table layout. It is thrown at open time for non-ReadOnly, non-Gateway configs. The wrapped err carries the root cause (migration SQL failure, connection drop, drift guard).

Source

Thrown at internal/storage/dolt/store.go:2026

		var verifyErr error
		if cfg.Database == doltserver.GlobalDatabaseName {
			verifyErr = store.verifyGlobalProjectIdentity(ctx, cfg.BeadsDir)
		} else {
			verifyErr = store.verifyProjectIdentity(ctx, cfg.BeadsDir)
		}
		if verifyErr != nil {
			return nil, verifyErr
		}
	}

	// A gateway server owns the schema: it provisions each project at its deployed bd
	// version, so a client must never run migrations (DDL) against it. Treat it like
	// ReadOnly for schema — the forward-drift guard above still protects a stale client
	// binary.
	if !cfg.ReadOnly && !cfg.Gateway {
		applied, err := store.initSchema(ctx, dbFacts.bootstrapHeal)
		if err != nil {
			return nil, fmt.Errorf("failed to initialize schema: %w", err)
		}
		// initSchema runs migrations over a separate pool (openMigrationDB).
		// The Ping above already pinned a connection in store.db to the
		// pre-migration session root; without a rebuild, the first read
		// through that stale connection returns 0 rows / table-not-found
		// and does not self-heal on retry (be-itm5). Only a migrating open
		// (applied > 0) needs this — rebuildPoolAfterMigration no-ops otherwise.
		if err := store.rebuildPoolAfterMigration(ctx, applied); err != nil {
			return nil, fmt.Errorf("failed to rebuild pool after migration: %w", err)
		}
	}

	if isLocalHost(cfg.ServerHost) {
		beadsDir := cfg.BeadsDir
		if beadsDir == "" && cfg.Path != "" {
			beadsDir = filepath.Dir(cfg.Path)
		}
		_ = persistResolvedPortFile(cfg, beadsDir)

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped err to identify the failing migration step
2. Verify the Dolt server is running and reachable (bd dolt status)
3. Check the DB user has DDL privileges
4. Upgrade or align the bd client binary with the server schema version
5. If drift/partial migration is suspected, restore from backup or let a healthy client run migrations

Example fix

// before
store, err := NewStore(ctx, cfg) // opaque failure
// after
store, err := NewStore(ctx, cfg)
if err != nil {
    var initErr *fmt.WrapError // inspect wrapped initSchema error
    log.Fatalf("schema init failed: %v", err)
}

if cfg.ReadOnly || cfg.Gateway { skip schema init } // else ensure server reachable first:
if err := db.PingContext(ctx); err != nil { return fmt.Errorf("server unreachable before schema init: %w", err) }

store, err := NewStore(ctx, cfg)
if err != nil {
    if strings.Contains(err.Error(), "failed to initialize schema") {
        // inspect wrapped cause, verify server, retry once
    }
    return err
}

When it happens

Trigger: Opening a DoltStore with cfg.ReadOnly=false and cfg.Gateway=false where store.initSchema(ctx, dbFacts.bootstrapHeal) returns an error — e.g. a migration SQL statement fails, the migrations table can't be written, or a bootstrap-heal step fails.

Common situations: Server restarted mid-migration leaving partial DDL; stale client binary against a newer schema (version drift); MySQL/Dolt server rejecting DDL due to permissions; network interruption during DDL.

Related errors

• ignored migrations: %w
• migration %s: %w
• clone from %s succeeded, but the database needs %d schema %s
• failed to recompute is_blocked: %w
• failed to migrate credential keys: %w

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