gastownhall/beads · critical

uow: database %q not found — the schema is managed by beads-

Error message

uow: database %q not found — the schema is managed by beads-team-server; ask your operator to run 'bts init' first: %w

What it means

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.

Source

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

		schema.WithDatabaseSelector(selectProbeDatabase),
		schema.WithLockedPreparation(p.serverEndpoint, preparer.prepare)); err != nil {
		return classifyInitSchemaError(err)
	}
	return nil
}

// verifyTeamServerSchema is the team-server open path: the schema is owned by
// beads-team-server (bts), so bd never creates the database or migrates. It
// attaches to the existing database and verifies the schema version, then the
// project identity — identity is checked only after the schema check proves the
// metadata table exists at this binary's version.
func (p *doltSQLProvider) verifyTeamServerSchema(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 — the schema is managed by beads-team-server; ask your operator to run 'bts init' first: %w",
			database, err))
	}
	if err := checkTeamServerSchema(ctx, conn, database); err != nil {
		if isSerializationError(err) {
			return fmt.Errorf("uow: team-server schema check: %w", err)
		}
		return backoff.Permanent(err)
	}
	if err := checkTeamServerIdentity(ctx, conn, database, p.expectedProjectID); err != nil {
		if isSerializationError(err) {
			return fmt.Errorf("uow: team-server identity check: %w", err)
		}
		return backoff.Permanent(err)
	}
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Ask the team-server operator to run 'bts init' to create and migrate the database.
2. Verify the database name in the workspace config matches one on the server (SHOW DATABASES).
3. Confirm you are connecting to the intended team-server endpoint (right environment).
4. If the database was dropped by accident, restore it from the team server's backups.

Example fix

// before (workspace config pointing at nonexistent db)
{"dolt": {"database": "team_issues_old"}}

// after
{"dolt": {"database": "team_issues"}} // database created by 'bts init'

// verify the team-server database exists before opening the provider
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
rows, err := adminConn.QueryContext(ctx, "SHOW DATABASES LIKE ?", dbName)
if err != nil { return err }
if !rows.Next() {
    return fmt.Errorf("database %q not found; ask the operator to run 'bts init'", dbName)
}

err := provider.Open(ctx, cfg)
if err != nil {
    if strings.Contains(err.Error(), "run 'bts init' first") {
        return fmt.Errorf("team-server not initialized: contact your operator — %w", err)
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• PROJECT IDENTITY MISMATCH — refusing to connect Local pro
• database %q not found on Dolt server at %s:%d
• failed to open database: %w Hint: %s
• loading status configuration: %w
• database not available: %w

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