{"record":{"id":"63774618d9ca3132","repo":"clockworklabs/SpacetimeDB","slug":"uri-is-required-to-connect-to-spacetimedb","errorCode":null,"errorMessage":"URI is required to connect to SpacetimeDB","messagePattern":"URI is required to connect to SpacetimeDB","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/sdk/db_connection_builder.ts","lineNumber":265,"sourceCode":"  }\n\n  /**\n   * Builds a new `DbConnection` with the parameters set on this `DbConnectionBuilder` and attempts to connect to the SpacetimeDB server.\n   *\n   * @returns A new `DbConnection` with the parameters set on this `DbConnectionBuilder`.\n   *\n   * @example\n   *\n   * ```ts\n   * const host = \"http://localhost:3000\";\n   * const name_or_address = \"database_name\"\n   * const auth_token = undefined;\n   * DbConnection.builder().withUri(host).withDatabaseName(name_or_address).withToken(auth_token).build();\n   * ```\n   */\n  build(): DbConnection {\n    if (!this.#uri) {\n      throw new Error('URI is required to connect to SpacetimeDB');\n    }\n\n    if (!this.#nameOrAddress) {\n      throw new Error(\n        'Database name or address is required to connect to SpacetimeDB'\n      );\n    }\n    // We could consider making this an `onConnectError` instead of throwing here.\n    // Ideally, it would be a compile time error, but I'm not sure how to accomplish that.\n    ensureMinimumVersionOrThrow(this.remoteModule.versionInfo?.cliVersion);\n\n    return this.dbConnectionCtor({\n      uri: this.#uri,\n      nameOrAddress: this.#nameOrAddress,\n      identity: this.#identity,\n      token: this.#token,\n      emitter: this.#emitter,\n      compression: this.#compression,","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/sdk/db_connection_builder.ts#L247-L283","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call .withUri('http://localhost:3000') (or your wss/http host) before .build()","Read the host from config with an explicit fallback and fail with your own clear message when it is unset","Add a startup assertion on required env vars so misconfiguration is caught in deploy checks, not at connect time"],"exampleFix":"// before\nconst conn = DbConnection.builder().withDatabaseName('mydb').build(); // throws\n\n// after\nconst uri = process.env.SPACETIMEDB_URI ?? 'http://localhost:3000';\nconst conn = DbConnection.builder().withUri(uri).withDatabaseName('mydb').build();","handlingStrategy":"validation","validationCode":"const uri = process.env.SPACETIMEDB_URI;\nif (!uri) throw new Error('SPACETIMEDB_URI is not set (use e.g. http://localhost:3000)');\nDbConnection.builder().withUri(uri).withDatabaseName(name).build();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate required connection config in one place before building the connection","Give env vars a dev default so missing config fails loudly only in deployed environments"],"tags":["configuration","connection","builder","typescript"],"backgroundTag":"missing-connection-config","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}