{"record":{"id":"428163bb1d592a8e","repo":"gastownhall/beads","slug":"uow-database-q-not-found-preview-commands-d","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/uow/dolt_sql_provider.go","lineNumber":279,"sourceCode":"\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: team-server identity check: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(err)\n\t}\n\treturn nil\n}\n\n// attachPreviewDatabase is the preview open path: attach to the database that is\n// already there and stop. No CreateDatabase, no MigrateUpWithLock — a --dry-run\n// or --inspect that migrated the workspace before rendering its plan would be the\n// exact side effect the flag exists to prevent.\nfunc (p *doltSQLProvider) attachPreviewDatabase(ctx context.Context, conn *sql.Conn, database string) error {\n\tddl := db.NewDDLSQLRepository(conn)\n\tif err := ddl.UseDatabase(ctx, database); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: switching to database: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(fmt.Errorf(\n\t\t\t\"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\",\n\t\t\tdatabase, err))\n\t}\n\treturn nil\n}\n\n// bootstrapPreparer carries the sticky fresh-bootstrap state across the backoff\n// retry attempts of a single initSchema call and runs as MigrateUpWithLock's\n// locked-preparation callback (see prepare).\n//\n// Fresh-bootstrap ownership proof for the #4566 guard self-heal\n// (gastownhall/beads#5012): the first attempt issues a bare CREATE DATABASE (no\n// IF NOT EXISTS), so the server arbitrates creation atomically — success proves\n// THIS init created the database, and an already-exists refusal (1007) proves it\n// did not. Only the proven creator captures and passes a one-shot\n// FreshBootstrapHealCapability: on a database this init created, a retry attempt\n// that finds dirty tables can only be seeing a previous attempt's own\n// half-applied migration step (a session that died between a step's SQL and its","sourceCodeStart":261,"sourceCodeEnd":297,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/dolt_sql_provider.go#L261-L297","documentation":"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.","triggerScenarios":"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').","commonSituations":"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.","solutions":["Run the same command once WITHOUT the preview flag — the normal path creates and migrates the database; afterwards preview works.","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').","Confirm you're pointed at the correct server endpoint where the workspace database actually lives."],"exampleFix":"// before\nbd doctor --dry-run   # fails: database \"beads_ws\" not found\n\n// after\nbd doctor              # creates + migrates the database\nbd doctor --dry-run    # preview now works","handlingStrategy":"validation","validationCode":"// Pre-flight check before any preview command:\nfunc ensureDatabaseExists(ctx context.Context, db *sql.DB, name string) error {\n\tvar unused string\n\terr := db.QueryRowContext(ctx,\n\t\t\"SELECT SCHEMA_NAME FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = ?\", name,\n\t).Scan(&unused)\n\tif errors.Is(err, sql.ErrNoRows) {\n\t\treturn fmt.Errorf(\"database %q not found — run once WITHOUT --dry-run/--inspect to create it\", name)\n\t}\n\treturn err\n}","typeGuard":"func isDatabaseNotFound(err error) bool {\n\treturn err != nil && strings.Contains(err.Error(), \"not found\") &&\n\t\tstrings.Contains(err.Error(), \"preview\")\n}","tryCatchPattern":"if err := runPreview(ctx); err != nil {\n\tif isDatabaseNotFound(err) {\n\t\tfmt.Fprintln(os.Stderr, \"Preview target not initialized. Running real command first...\")\n\t\tif err := runReal(ctx); err != nil { return err }\n\t\treturn runPreview(ctx)\n\t}\n\treturn err\n}","preventionTips":["Never run --dry-run/--inspect against a brand-new workspace path; initialize first with a real command.","Double-check the database name in BEADS_DB / DSN configuration before previewing.","Confirm you are pointed at the server endpoint where the workspace database actually exists.","Check that a scheduled clean-databases job is not dropping the target database."],"tags":["dolt","preview","dry-run","database-not-found","unit-of-work"],"backgroundTag":"database-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}