{"record":{"id":"72453f17ac0c254a","repo":"clockworklabs/SpacetimeDB","slug":"database-name-or-address-is-required-to-connect-to","errorCode":null,"errorMessage":"Database name or address is required to connect to SpacetimeDB","messagePattern":"Database name or address 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":269,"sourceCode":"   *\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,\n      lightMode: this.#lightMode,\n      confirmedReads: this.#confirmedReads,\n      createWSFn: this.#createWSFn,\n      remoteModule: this.remoteModule,","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/sdk/db_connection_builder.ts#L251-L287","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call .withDatabaseName('database_name') (or .withAddress('<address>')) before .build()","Default the name in dev config and assert on it in production startup","Keep URI and database name validation together in one config check so both fail with one clear message"],"exampleFix":"// before\nconst conn = DbConnection.builder().withUri(uri).build(); // throws\n\n// after\nconst conn = DbConnection.builder().withUri(uri).withDatabaseName('mydb').build();","handlingStrategy":"validation","validationCode":"const dbName = process.env.SPACETIMEDB_DATABASE;\nif (!uri || !dbName) {\n  throw new Error(`missing connection config: uri=${!!uri} database=${!!dbName}`);\n}\nDbConnection.builder().withUri(uri).withDatabaseName(dbName).build();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep URI and database name checks together in a single config validator","Assert on required config during deployment smoke tests, not at first user connect"],"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"}