tursodatabase/turso · error · LibsqlError

NOT_SUPPORTED

NOT_SUPPORTED

Error message

Sync not supported for remote databases

What it means

`sync()` exists on the client interface but this HTTP-only remote client throws NOT_SUPPORTED unconditionally. Syncing offline state is only meaningful for clients backed by a local embedded replica; a pure network connection has nothing to sync, so the method is a hard stub.

Solutions

1. Remove the sync() call for remote connections
2. Gate sync behind a client-type or config check
3. If offline sync is required, switch to a sync-capable setup (local file + embedded replica)

Example fix

// before
await client.sync();
// after
if (config.localPath) {
  await replicaClient.sync(); // embedded replica only
}

try {
  await client.sync();
} catch (e) {
  if (e instanceof LibsqlError && e.code === 'NOT_SUPPORTED') {
    // remote client: nothing to sync, skip
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling `await client.sync()` on a remote/serverless connection; shared app code that unconditionally syncs after migrations or on a schedule.

Common situations: Code shared between an embedded-replica deployment and a remote-only one; porting from an SDK or CLI where sync is supported; assuming the full client interface is implemented everywhere.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• No active remote transaction
• Sync requires an embedded replica connection.
• Auth Token requires an HTTPS sync URL unless the host is…
• Auth Token requires HTTPS sync requests unless the host is…
• Automatic sync is not supported for embedded replica…

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

Appendix: source

Thrown at serverless/javascript/src/compat.ts:518

    await this.execLock.acquire();
    try {
      if (this._closed) {
        throw new LibsqlError("Client is closed", "CLIENT_CLOSED");
      }

      await this.session.sequence(sql);
    } catch (error: any) {
      if (error instanceof LibsqlError) {
        throw error;
      }
      throw mapDatabaseError(error, "EXECUTE_MULTIPLE_ERROR");
    } finally {
      this.execLock.release();
    }
  }

  async sync(): Promise<any> {
    throw new LibsqlError("Sync not supported for remote databases", "NOT_SUPPORTED");
  }

  close(): void {
    this._closed = true;
    // Note: The libSQL client interface expects synchronous close,
    // but our underlying session needs async close. We'll fire and forget.
    this.session.close().catch(error => {
      console.error('Error closing session:', error);
    });
  }

  reconnect(): void {
    const wasOpen = !this._closed;
    this._closed = false;

    if (wasOpen) {
      this.session.close().catch(error => {
        console.error('Error closing session during reconnect:', error);

View on GitHub (pinned to 6c72522679)