tursodatabase/turso · error · Error

checkpoint() is only available for sync databases

Error message

checkpoint() is only available for sync databases

What it means

checkpoint() runs the native sync database's checkpoint operation to truncate the local WAL after synchronization. As with the other sync-only methods, it requires _isSync (url present in opts), plus the _nativeSyncDb and _ioContext that connect() creates in sync mode; otherwise it throws. A local-only database manages its WAL through the regular query path, not through this API.

Source

Thrown at bindings/react-native/src/Database.ts:400

   * Get sync statistics (sync databases only)
   *
   * @returns Sync stats
   */
  async stats(): Promise<SyncStats> {
    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {
      throw new Error('stats() is only available for sync databases');
    }

    const operation = this._nativeSyncDb.stats();
    return driveStatsOperation(operation, this._nativeSyncDb, this._ioContext);
  }

  /**
   * Checkpoint database (sync databases only)
   */
  async checkpoint(): Promise<void> {
    if (!this._isSync || !this._nativeSyncDb || !this._ioContext) {
      throw new Error('checkpoint() is only available for sync databases');
    }

    const operation = this._nativeSyncDb.checkpoint();
    await driveVoidOperation(operation, this._nativeSyncDb, this._ioContext);
  }

  /**
   * Close the database
   */
  close(): void {
    if (this._closed) {
      return;
    }

    if (this._connection) {
      this._connection.close();
      this._connection = null;
    }

View on GitHub (pinned to bad083fafb)

Solutions

1. Construct the database with `url` and `authToken` so sync mode is active
2. Call `await db.connect()` before checkpoint(), typically after push/pull cycles
3. Remove the call for databases that intentionally stay local-only

Example fix

// before
const db = new Database({ path: 'app.db' });
await db.checkpoint(); // throws

// after
const db = new Database({ path: 'app.db', url, authToken });
await db.connect();
await db.pull();
await db.checkpoint();

if (isSyncConfig(opts)) {
  await db.connect();
  await db.push();
  await db.checkpoint(); // only after a successful sync-mode connect
}

try { await db.checkpoint(); } catch (e) { if (e instanceof Error && e.message.includes('only available for sync databases')) return; throw e; }

When it happens

Trigger: `new Database({ path })` with no url followed by `await db.checkpoint()`; maintenance code that checkpoints on a schedule or after N writes running against a local-mode handle; calling checkpoint() before connect() completes.

Common situations: Porting WAL-management logic from the WASM sync binding to React Native without enabling sync config; background jobs that treat every database as synced; startup sequences that checkpoint before connect resolves.

Related errors

• push() is only available for sync databases
• pull() is only available for sync databases
• stats() is only available for sync databases
• HTTP request missing URL: no URL in request and no baseUrl i
• remoteWritesExperimental requires a non-null URL

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/6f2f154801f75a6e. Report an issue: GitHub.