{"record":{"id":"f21b4c22ec341e15","repo":"tursodatabase/turso","slug":"push-is-only-available-for-sync-databases","errorCode":null,"errorMessage":"push() is only available for sync databases","messagePattern":"push\\(\\) is only available for sync databases","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"bindings/react-native/src/Database.ts","lineNumber":348,"sourceCode":"  async transaction<T>(fn: () => T | Promise<T>): Promise<T> {\n    this.checkOpen();\n    await this.exec('BEGIN');\n    try {\n      const result = await fn();\n      await this.exec('COMMIT');\n      return result;\n    } catch (error) {\n      await this.exec('ROLLBACK');\n      throw error;\n    }\n  }\n\n  /**\n   * Push local changes to remote (sync databases only)\n   */\n  async push(): Promise<void> {\n    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {\n      throw new Error('push() is only available for sync databases');\n    }\n\n    const operation = this._nativeSyncDb.pushChanges();\n    await driveVoidOperation(operation, this._nativeSyncDb, this._ioContext);\n  }\n\n  /**\n   * Pull remote changes and apply locally (sync databases only)\n   *\n   * @returns true if changes were applied, false if no changes\n   */\n  async pull(): Promise<boolean> {\n    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {\n      throw new Error('pull() is only available for sync databases');\n    }\n\n    // Wait for changes\n    const waitOperation = this._nativeSyncDb.waitChanges();","sourceCodeStart":330,"sourceCodeEnd":366,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/react-native/src/Database.ts#L330-L366","documentation":"push() requires a sync-mode database: _isSync true, a native sync database handle (_nativeSyncDb, created by initSyncDatabase when the `url` option is present), and an _ioContext for driving the native operation loop. If the Database was constructed without a url it is local-only and has no remote to push to, so the call is rejected before touching the network.","triggerScenarios":"Calling await db.push() on a Database created with only `{ path }` (local-only), or on a sync-configured database before connect() has created _nativeSyncDb/_ioContext. Also when a typo'd option key (e.g. `urls:` instead of `url:`) silently makes isSyncConfig() return false.","commonSituations":"Starting a project local-only then adding sync calls without updating the Database constructor; development builds pointing at a config object where url is conditionally undefined; calling push() before awaiting db.connect().","solutions":["Construct the database with sync options: new Database({ path: getDbPath('app.db'), url: 'libsql://...turso.io', authToken })","Await db.connect() before calling push() so the sync handle and IO context exist","Guard the call with the `db.isSync` getter (or track it yourself) in code shared between local and sync deployments","Check the option spelling — only `url` (string or function returning a string) enables sync mode"],"exampleFix":"// before\nconst db = new Database({ path: getDbPath('app.db') });\nawait db.connect();\nawait db.push(); // throws: local-only database\n\n// after\nconst db = new Database({\n  path: getDbPath('app.db'),\n  url: 'libsql://my-db.turso.io',\n  authToken: token,\n});\nawait db.connect();\nawait db.push();","handlingStrategy":"type-guard","validationCode":"if (!db.isSync) {\n  throw new Error('push() called on a local-only database — construct Database with url + authToken');\n}\nawait db.push();","typeGuard":"function isSyncDatabase(db: Database): boolean {\n  return db.isSync; // true only when constructed with a `url` option\n}","tryCatchPattern":"try {\n  await db.push();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('only available for sync databases')) {\n    // Configuration bug, not transient: fix construction; do not retry\n    throw new Error('Misconfigured Database: add url/authToken options to enable sync');\n  }\n  throw e;\n}","preventionTips":["Construct the Database in exactly one place with the full sync config so all callers share it","Guard all sync calls with db.isSync when the app supports a local-only mode","Always await db.connect() before push/pull/stats/checkpoint"],"tags":["react-native","sync","api-misuse","embedded-replicas"],"backgroundTag":"sync-mode-required","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}