clockworklabs/SpacetimeDB · error · Error

URI is required to connect to SpacetimeDB

Error message

URI is required to connect to SpacetimeDB

What it means

DbConnection.builder().build() performs fail-fast config validation: both a URI (set with withUri) and a database name or address (withDatabaseName/withAddress) must be present before a connection object is constructed. A missing or empty URI throws immediately instead of failing later during the WebSocket handshake.

Source

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

  }

  /**
   * Builds a new `DbConnection` with the parameters set on this `DbConnectionBuilder` and attempts to connect to the SpacetimeDB server.
   *
   * @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,

View on GitHub (pinned to 524b4487d9)

Solutions

1. Call .withUri('http://localhost:3000') (or your wss/http host) before .build()
2. Read the host from config with an explicit fallback and fail with your own clear message when it is unset
3. Add a startup assertion on required env vars so misconfiguration is caught in deploy checks, not at connect time

Example fix

// before
const conn = DbConnection.builder().withDatabaseName('mydb').build(); // throws

// after
const uri = process.env.SPACETIMEDB_URI ?? 'http://localhost:3000';
const conn = DbConnection.builder().withUri(uri).withDatabaseName('mydb').build();

const uri = process.env.SPACETIMEDB_URI;
if (!uri) throw new Error('SPACETIMEDB_URI is not set (use e.g. http://localhost:3000)');
DbConnection.builder().withUri(uri).withDatabaseName(name).build();

When it happens

Trigger: Calling .build() without .withUri(...) - e.g. the URI came from an env var that is undefined or empty in the current environment, or the withUri call was removed during a refactor.

Common situations: Missing SPACETIMEDB_URI in production/CI while it is set locally; deploying a bundle built with a different env pipeline; a code path that conditionally sets the URI and skips it.

Related errors

• Database name or address is required to connect to Spacetime
• 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/63774618d9ca3132. Report an issue: GitHub.