{"record":{"id":"c8660f1b123f3c27","repo":"tursodatabase/turso","slug":"stats-is-only-available-for-sync-databases","errorCode":null,"errorMessage":"stats() is only available for sync databases","messagePattern":"stats\\(\\) is only available for sync databases","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/react-native/src/Database.ts","lineNumber":388,"sourceCode":"    if (!changes) {\n      return false;\n    }\n\n    // Apply changes\n    const applyOperation = this._nativeSyncDb.applyChanges(changes);\n    await driveVoidOperation(applyOperation, this._nativeSyncDb, this._ioContext);\n\n    return true;\n  }\n\n  /**\n   * Get sync statistics (sync databases only)\n   *\n   * @returns Sync stats\n   */\n  async stats(): Promise<SyncStats> {\n    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {\n      throw new Error('stats() is only available for sync databases');\n    }\n\n    const operation = this._nativeSyncDb.stats();\n    return driveStatsOperation(operation, this._nativeSyncDb, this._ioContext);\n  }\n\n  /**\n   * Checkpoint database (sync databases only)\n   */\n  async checkpoint(): Promise<void> {\n    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {\n      throw new Error('checkpoint() is only available for sync databases');\n    }\n\n    const operation = this._nativeSyncDb.checkpoint();\n    await driveVoidOperation(operation, this._nativeSyncDb, this._ioContext);\n  }\n","sourceCodeStart":370,"sourceCodeEnd":406,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/react-native/src/Database.ts#L370-L406","documentation":"stats() returns SyncStats by driving the native sync database's stats() operation; it requires the full sync setup (_isSync, _nativeSyncDb, _ioContext). On a local-only database these handles were never created, so the metrics the method reports (sync frame/transfer statistics) do not exist and the call is rejected.","triggerScenarios":"Calling await db.stats() on a Database constructed with only `{ path }`, or before `await db.connect()` completed on a sync database. Any of the three guard conditions missing triggers it.","commonSituations":"A diagnostics/debug screen that calls stats() unconditionally while the app supports a local-only mode; monitoring code written against a sync dev environment then shipped to a build where url is not configured.","solutions":["Configure the database for sync (url + authToken options) and await connect() before calling stats()","Guard diagnostics UI with `db.isSync` and hide/disable stats for local-only databases","Centralize the Database construction so every caller gets the same sync/local configuration"],"exampleFix":"// before\nasync function showSyncStats(db) {\n  const stats = await db.stats(); // throws on local-only db\n}\n\n// after\nasync function showSyncStats(db) {\n  if (!db.isSync) return null;\n  return await db.stats();\n}","handlingStrategy":"type-guard","validationCode":"if (!db.isSync) {\n  return null; // stats only exist for sync databases\n}\nreturn await db.stats();","typeGuard":"function isSyncDb(db: Database): boolean {\n  return db.isSync;\n}","tryCatchPattern":"try {\n  return await db.stats();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('only available for sync databases')) {\n    return null; // diagnostics UI renders 'sync disabled'\n  }\n  throw e;\n}","preventionTips":["Hide or disable sync-stats UI when db.isSync is false","Centralize Database construction so diagnostics code cannot run against a differently-configured instance"],"tags":["react-native","sync","api-misuse","stats"],"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"}