{"record":{"id":"f3212939ee7a7e9e","repo":"gastownhall/beads","slug":"uow-database-q-not-found-the-schema-is-managed","errorCode":null,"errorMessage":"uow: database %q not found — the schema is managed by beads-team-server; ask your operator to run 'bts init' first: %w","messagePattern":"uow: database %q not found — the schema is managed by beads-team-server; ask your operator to run 'bts init' first: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/storage/uow/dolt_sql_provider.go","lineNumber":250,"sourceCode":"\t\tschema.WithDatabaseSelector(selectProbeDatabase),\n\t\tschema.WithLockedPreparation(p.serverEndpoint, preparer.prepare)); err != nil {\n\t\treturn classifyInitSchemaError(err)\n\t}\n\treturn nil\n}\n\n// verifyTeamServerSchema is the team-server open path: the schema is owned by\n// beads-team-server (bts), so bd never creates the database or migrates. It\n// attaches to the existing database and verifies the schema version, then the\n// project identity — identity is checked only after the schema check proves the\n// metadata table exists at this binary's version.\nfunc (p *doltSQLProvider) verifyTeamServerSchema(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 — the schema is managed by beads-team-server; ask your operator to run 'bts init' first: %w\",\n\t\t\tdatabase, err))\n\t}\n\tif err := checkTeamServerSchema(ctx, conn, database); err != nil {\n\t\tif isSerializationError(err) {\n\t\t\treturn fmt.Errorf(\"uow: team-server schema check: %w\", err)\n\t\t}\n\t\treturn backoff.Permanent(err)\n\t}\n\tif err := checkTeamServerIdentity(ctx, conn, database, p.expectedProjectID); err != nil {\n\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","sourceCodeStart":232,"sourceCodeEnd":268,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/uow/dolt_sql_provider.go#L232-L268","documentation":"The terminal branch of the team-server USE check: switching to the configured database fails with a non-serialization error, so verifyTeamServerSchema returns backoff.Permanent with an explicit operator-facing message: the database does not exist and, because the schema is owned by beads-team-server, bd will not create it.","triggerScenarios":"initSchemaAttempt (teamServer=true) against a beads-team-server where the expected database was never created ('bts init' never run), or the workspace's configured database name doesn't match any database on the server.","commonSituations":"Operator forgot to run 'bts init' on a fresh team server; workspace .beads config pointing at a database name that was renamed or dropped; connecting to the wrong team-server environment (staging vs prod).","solutions":["Ask the team-server operator to run 'bts init' to create and migrate the database.","Verify the database name in the workspace config matches one on the server (SHOW DATABASES).","Confirm you are connecting to the intended team-server endpoint (right environment).","If the database was dropped by accident, restore it from the team server's backups."],"exampleFix":"// before (workspace config pointing at nonexistent db)\n{\"dolt\": {\"database\": \"team_issues_old\"}}\n\n// after\n{\"dolt\": {\"database\": \"team_issues\"}} // database created by 'bts init'","handlingStrategy":"validation","validationCode":"// verify the team-server database exists before opening the provider\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\ndefer cancel()\nrows, err := adminConn.QueryContext(ctx, \"SHOW DATABASES LIKE ?\", dbName)\nif err != nil { return err }\nif !rows.Next() {\n    return fmt.Errorf(\"database %q not found; ask the operator to run 'bts init'\", dbName)\n}","typeGuard":null,"tryCatchPattern":"err := provider.Open(ctx, cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"run 'bts init' first\") {\n        return fmt.Errorf(\"team-server not initialized: contact your operator — %w\", err)\n    }\n    return err\n}","preventionTips":["Always run 'bts init' on a fresh team server before distributing client configs.","Keep the database name in workspace .beads config in sync with the server.","Document the staging vs prod endpoints to avoid connecting to the wrong server.","Add a smoke test that SHOW DATABASES matches the configured name."],"tags":["database","team-server","missing-database","configuration"],"backgroundTag":"database-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}