tursodatabase/turso · error · NotSupportedException

Sync requires an embedded replica connection.

Error message

Sync requires an embedded replica connection.

What it means

SyncAsync only permits the sync code path for embedded-replica connections: IsReplica is true only when Data Source has a remote scheme (libsql/http/https/ws/wss) AND 'Replica Path' is non-empty. Any other open connection — a local file database or a direct remote connection without Replica Path — fails this guard with NotSupportedException before any work is done.

Source

Thrown at bindings/dotnet/src/Turso.Data/TursoConnection.cs:160

        command.CommandText = sql;

        return command.ExecuteNonQuery();
    }

    public void Sync()
    {
        SyncAsync(CancellationToken.None).GetAwaiter().GetResult();
    }

    public Task SyncAsync(CancellationToken cancellationToken = default)
    {
        ObjectDisposedException.ThrowIf(_disposed, this);
        if (cancellationToken.IsCancellationRequested)
            return Task.FromCanceled(cancellationToken);
        if (State != ConnectionState.Open)
            throw new InvalidOperationException("Turso database is closed.");
        if (!_connectionOptions.IsReplica)
            throw new NotSupportedException("Sync requires an embedded replica connection.");

        throw new NotSupportedException("Embedded replica sync is not supported yet by the .NET provider.");
    }

    public override void ChangeDatabase(string databaseName)
    {
        throw new NotSupportedException("Turso does not support changing the active database.");
    }

    internal int DefaultTimeout => _connectionOptions.DefaultTimeout;

    internal bool IsRemote => _remoteClient is not null;

    internal bool ReadUncommitted
    {
        get => _readUncommitted;
        set => _readUncommitted = value;
    }

View on GitHub (pinned to 244cde92a7)

Solutions

  1. Remove the Sync()/SyncAsync() call — with a direct remote connection (no Replica Path) every command already executes against the server, so there is nothing to flush
  2. If you actually want an embedded replica, add 'Replica Path' to a remote connection string — but the .NET provider then throws 'Embedded replica sync is not supported yet' instead
  3. Confirm Data Source is remote (libsql:// or https://); a local file connection can never sync

Example fix

// before
var cs = "Data Source=libsql://db.turso.io;Auth Token=...";
using var conn = new TursoConnection(cs);
conn.Open();
await conn.SyncAsync(); // NotSupportedException: not a replica

// after
var cs = "Data Source=libsql://db.turso.io;Auth Token=...";
using var conn = new TursoConnection(cs);
conn.Open();
// direct remote: statements already run on the server; drop the Sync call
Defensive patterns

Strategy: validation

Validate before calling

var opts = TursoConnectionOptions.Parse(cs);
if (opts.IsReplica)
{
    // .NET provider cannot sync replicas either (see NotSupportedException) -- do not call Sync
}
else
{
    // direct remote or local: Sync is not applicable; every statement already executes remotely
}

Try / catch

try { await conn.SyncAsync(ct); }
catch (NotSupportedException) { /* sync not applicable to this connection mode */ }

Prevention

When it happens

Trigger: conn.Sync() with Data Source pointing at a local file (app.db); conn.Sync() on a direct remote URL whose connection string lacks 'Replica Path=...'; reassigning ConnectionString to a non-replica value after opening.

Common situations: Code ported from Turso's Rust/Python/JS SDKs where sync is part of the workflow; assuming direct remote connections need a sync flush (they execute every statement server-side already); misspelling the 'Replica Path' keyword so it silently stays empty.

Related errors

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