clockworklabs/SpacetimeDB · error · Error

Database name or address is required to connect to Spacetime

Error message

Database name or address is required to connect to SpacetimeDB

What it means

DbConnection.builder().build() requires a database name or address in addition to the URI. The check is the second half of the builder's fail-fast validation: without a nameOrAddress the SDK has nothing to resolve on the server, so it throws before constructing the connection.

Source

Thrown at crates/bindings-typescript/src/sdk/db_connection_builder.ts:269

   *
   * @returns A new `DbConnection` with the parameters set on this `DbConnectionBuilder`.
   *
   * @example
   *
   * ```ts
   * const host = "http://localhost:3000";
   * const name_or_address = "database_name"
   * const auth_token = undefined;
   * DbConnection.builder().withUri(host).withDatabaseName(name_or_address).withToken(auth_token).build();
   * ```
   */
  build(): DbConnection {
    if (!this.#uri) {
      throw new Error('URI is required to connect to SpacetimeDB');
    }

    if (!this.#nameOrAddress) {
      throw new Error(
        'Database name or address is required to connect to SpacetimeDB'
      );
    }
    // We could consider making this an `onConnectError` instead of throwing here.
    // Ideally, it would be a compile time error, but I'm not sure how to accomplish that.
    ensureMinimumVersionOrThrow(this.remoteModule.versionInfo?.cliVersion);

    return this.dbConnectionCtor({
      uri: this.#uri,
      nameOrAddress: this.#nameOrAddress,
      identity: this.#identity,
      token: this.#token,
      emitter: this.#emitter,
      compression: this.#compression,
      lightMode: this.#lightMode,
      confirmedReads: this.#confirmedReads,
      createWSFn: this.#createWSFn,
      remoteModule: this.remoteModule,

View on GitHub (pinned to 524b4487d9)

Solutions

1. Call .withDatabaseName('database_name') (or .withAddress('<address>')) before .build()
2. Default the name in dev config and assert on it in production startup
3. Keep URI and database name validation together in one config check so both fail with one clear message

Example fix

// before
const conn = DbConnection.builder().withUri(uri).build(); // throws

// after
const conn = DbConnection.builder().withUri(uri).withDatabaseName('mydb').build();

const dbName = process.env.SPACETIMEDB_DATABASE;
if (!uri || !dbName) {
  throw new Error(`missing connection config: uri=${!!uri} database=${!!dbName}`);
}
DbConnection.builder().withUri(uri).withDatabaseName(dbName).build();

When it happens

Trigger: Calling .build() without .withDatabaseName(name) or .withAddress(address) - e.g. the database name was expected to come from a config file or CLI arg that is empty in this environment.

Common situations: Config rename (DB_NAME vs DATABASE_NAME) leaving the value undefined; a new deployment stage missing the database identifier; multi-tenant code paths where the name is passed conditionally.

Related errors

• URI is required to connect to SpacetimeDB
• Building DbConnection with a null uri. Call WithUri() first.
• Building DbConnection with a null nameOrAddress. Call WithDa
• cannot serialize refs without a typespace
• cannot deserialize refs without a typespace

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/72453f17ac0c254a. Report an issue: GitHub.