gastownhall/beads · error

uow: database %q not found — preview commands (--dry-run, --

Error message

uow: database %q not found — preview commands (--dry-run, --inspect) never create or migrate a database; run the command without the preview flag first: %w

What it means

This terminal error occurs when a preview command (--dry-run / --inspect) tries to USE a database that does not exist on the Dolt server. Preview mode deliberately performs no CreateDatabase and no migrations, so previewing a never-initialized workspace cannot proceed. It is returned via backoff.Permanent, meaning no retry will be attempted.

Source

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

		if isSerializationError(err) {
			return fmt.Errorf("uow: team-server identity check: %w", err)
		}
		return backoff.Permanent(err)
	}
	return nil
}

// attachPreviewDatabase is the preview open path: attach to the database that is
// already there and stop. No CreateDatabase, no MigrateUpWithLock — a --dry-run
// or --inspect that migrated the workspace before rendering its plan would be the
// exact side effect the flag exists to prevent.
func (p *doltSQLProvider) attachPreviewDatabase(ctx context.Context, conn *sql.Conn, database string) error {
	ddl := db.NewDDLSQLRepository(conn)
	if err := ddl.UseDatabase(ctx, database); err != nil {
		if isSerializationError(err) {
			return fmt.Errorf("uow: switching to database: %w", err)
		}
		return backoff.Permanent(fmt.Errorf(
			"uow: database %q not found — preview commands (--dry-run, --inspect) never create or migrate a database; run the command without the preview flag first: %w",
			database, err))
	}
	return nil
}

// bootstrapPreparer carries the sticky fresh-bootstrap state across the backoff
// retry attempts of a single initSchema call and runs as MigrateUpWithLock's
// locked-preparation callback (see prepare).
//
// Fresh-bootstrap ownership proof for the #4566 guard self-heal
// (gastownhall/beads#5012): the first attempt issues a bare CREATE DATABASE (no
// IF NOT EXISTS), so the server arbitrates creation atomically — success proves
// THIS init created the database, and an already-exists refusal (1007) proves it
// did not. Only the proven creator captures and passes a one-shot
// FreshBootstrapHealCapability: on a database this init created, a retry attempt
// that finds dirty tables can only be seeing a previous attempt's own
// half-applied migration step (a session that died between a step's SQL and its

View on GitHub (pinned to 71377f2769)

Solutions

1. Run the same command once WITHOUT the preview flag — the normal path creates and migrates the database; afterwards preview works.
2. Verify the database name in your configuration (BEADS_DB / DSN) matches an existing database (e.g. via SHOW DATABASES or dolt sql -q 'show databases').
3. Confirm you're pointed at the correct server endpoint where the workspace database actually lives.

Example fix

// before
bd doctor --dry-run   # fails: database "beads_ws" not found

// after
bd doctor              # creates + migrates the database
bd doctor --dry-run    # preview now works

// Pre-flight check before any preview command:
func ensureDatabaseExists(ctx context.Context, db *sql.DB, name string) error {
	var unused string
	err := db.QueryRowContext(ctx,
		"SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = ?", name,
	).Scan(&unused)
	if errors.Is(err, sql.ErrNoRows) {
		return fmt.Errorf("database %q not found — run once WITHOUT --dry-run/--inspect to create it", name)
	}
	return err
}

func isDatabaseNotFound(err error) bool {
	return err != nil && strings.Contains(err.Error(), "not found") &&
		strings.Contains(err.Error(), "preview")
}

if err := runPreview(ctx); err != nil {
	if isDatabaseNotFound(err) {
		fmt.Fprintln(os.Stderr, "Preview target not initialized. Running real command first...")
		if err := runReal(ctx); err != nil { return err }
		return runPreview(ctx)
	}
	return err
}

When it happens

Trigger: Running bd --dry-run or --inspect pointed at a workspace whose database was never created/migrated (initSchemaAttempt with p.preview=true and ddl.UseDatabase failing with a non-serialization error such as MySQL error 1049 'Unknown database').

Common situations: Pointing a preview command at a fresh checkout or new workspace path before ever running a real (non-preview) command; a typo'd BEADS_DB / database name; a database dropped by concurrent clean-databases; switching between server endpoints where the database only exists on the other one.

Related errors

• failed to initialize remote cache: %w
• dry-run parent lookup requires an existing cached remote sto
• failed to open target store for dry-run: %w
• uow: team-server identity check: %w
• uow: creating database: %w

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