gastownhall/beads · error

uow: init schema: %w

Error message

uow: init schema: %w

What it means

This error wraps any failure that occurs while initializing the database schema during NewDoltServerUOWProvider construction. openAndInitSchema connects to the Dolt SQL server without a default database and calls initSchema, which creates the database, tables, and verifies project identity. The connection is closed and the wrapped cause is returned so the caller knows provider startup (not later operation) failed.

Source

Thrown at internal/storage/uow/dolt_sql_provider.go:409

func openAndInitSchema(ctx context.Context, ep proxy.Endpoint, database, rootUser, rootPassword, tlsConfigName string, teamServer bool, expectedProjectID string, opts providerOptions) (UnitOfWorkProvider, error) {
	initDB, err := openDB(ctx, buildDSN(ep, "", rootUser, rootPassword, tlsConfigName))
	if err != nil {
		return nil, err
	}

	initProvider := &doltSQLProvider{
		defaultBranch:     defaultBranch,
		db:                initDB,
		serverEndpoint:    "tcp:" + ep.Address(),
		teamServer:        teamServer,
		expectedProjectID: expectedProjectID,
		preview:           opts.preview,
	}

	if err := initProvider.initSchema(ctx, database); err != nil {
		_ = initDB.Close()
		return nil, fmt.Errorf("uow: init schema: %w", err)
	}

	if err := initDB.Close(); err != nil {
		return nil, fmt.Errorf("uow: close init db: %w", err)
	}

	dbConn, err := openDB(ctx, buildDSN(ep, database, rootUser, rootPassword, tlsConfigName))
	if err != nil {
		return nil, err
	}

	return &doltSQLProvider{
		defaultBranch:     defaultBranch,
		db:                dbConn,
		serverEndpoint:    "tcp:" + ep.Address(),
		teamServer:        teamServer,
		expectedProjectID: expectedProjectID,
		preview:           opts.preview,

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause after 'uow: init schema:' to identify the actual SQL/permission failure
2. Verify the Dolt SQL server is running and reachable at the endpoint returned by the proxy
3. Check root user/password grants allow CREATE DATABASE and DDL
4. If caused by a corrupt/partial database from a prior failed init, drop the database or remove the server root dir and retry
5. If it is a project-identity mismatch, confirm expectedProjectID matches the existing database or re-initialize

Example fix

// before
prov, err := NewDoltServerUOWProvider(ctx, dir, "", log, cfg, backend, "root", "", "dolt", 0, 0, false, projectID)
// after (empty/nil expectedProjectID or mismatch is a common cause; also ensure server is up)
if err := waitUntilProxyReady(ctx, ep); err != nil { return err }
prov, err := NewDoltServerUOWProvider(ctx, dir, "beads", log, cfg, backend, "root", "", "dolt", 0, 0, false, projectID)

// Go: verify server reachability before constructing
conn, err := sql.Open("mysql", dsnNoDB)
if err == nil {
    if perr := conn.PingContext(ctx); perr != nil { return fmt.Errorf("dolt server unreachable: %w", perr) }
    conn.Close()
}

func isSchemaInitError(err error) bool {
    return err != nil && strings.Contains(err.Error(), "uow: init schema:")
}

prov, err := NewDoltServerUOWProvider(...)
if err != nil {
    var ne net.Error
    if errors.As(err, &ne) { /* server down: retry with backoff */ }
    if strings.Contains(err.Error(), "already exists") { /* drop/reinit stale db */ }
    return fmt.Errorf("provider init failed: %w", err)
}

When it happens

Trigger: Calling NewDoltServerUOWProvider or NewExternalDoltServerUOWProvider when initSchema fails: the SQL server is unreachable or ping fails, CREATE DATABASE / DDL statements fail (permissions, syntax, existing conflicting schema), or the expectedProjectID/preview identity check fails.

Common situations: Dolt server not yet running or crashed at startup; root credentials wrong so DDL is denied; a stale or partially-created database from an interrupted run; schema version mismatch after upgrading beads against an old database; expectedProjectID mismatch when pointing at an existing repo's database.

Related errors

• failed to recompute is_blocked: %w
• failed to scan comment: %w
• failed to initialize schema: %w
• ignored migrations: %w
• migration %s: %w

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