{"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/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/react-native/src/Database.ts#L370-L406","documentation":"stats() returns SyncStats from the native sync database (driven through driveStatsOperation with the IO context). It is only meaningful for sync databases, and the guard throws unless the constructor saw a url AND connect() successfully created _nativeSyncDb and _ioContext. On a local-only database there are no sync statistics to report.","triggerScenarios":"`new Database({ path })` without url followed by `await db.stats()`; a debug/telemetry panel calling stats() on a database whose connect() has not run or failed; sharing analytics code across local and synced app flavors.","commonSituations":"Adding a sync-health dashboard to an app that still opens the database locally; telemetry initialized before connection completes; build flavors where only one has the url configured.","solutions":["Open the database in sync mode by passing `url` and `authToken` in the constructor options","Ensure `await db.connect()` succeeded before requesting stats","Gate the dashboard/telemetry call behind the same flag that decides sync mode"],"exampleFix":"// before\nconst db = new Database({ path: 'app.db' });\nconst s = await db.stats(); // throws\n\n// after\nconst db = new Database({ path: 'app.db', url, authToken });\nawait db.connect();\nconst s = await db.stats();","handlingStrategy":"validation","validationCode":"const isSyncConfig = (o: DatabaseOpts) => o.url != null;\n\nasync function syncStats(db: Database, o: DatabaseOpts): Promise<SyncStats | null> {\n  if (!isSyncConfig(o)) return null;\n  await db.connect();\n  return db.stats();\n}","typeGuard":null,"tryCatchPattern":"try { return await db.stats(); } catch (e) { if (e instanceof Error && e.message.includes('only available for sync databases')) return null; throw e; }","preventionTips":["Show stats panels only for synced database handles","Keep the constructor opts reachable from telemetry code","Ensure connect() completed before sampling stats"],"tags":["react-native","sync","stats","configuration","lifecycle"],"backgroundTag":"feature-not-enabled","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}