tursodatabase/turso · error · NotSupportedException

Automatic sync is not supported for embedded replica connect

Error message

Automatic sync is not supported for embedded replica connections yet. Set Sync Interval=0 and call SyncAsync explicitly.

What it means

Automatic background sync on an interval is not implemented for embedded replica connections in the .NET Turso driver. ValidateReplicaOptions() throws NotSupportedException when a non-zero 'Sync Interval' is set, telling you to drive syncs manually with SyncAsync().

Source

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

                ? null
                : _connectionOptions.PushOperationsThreshold,
            PullBytesThreshold = _connectionOptions.PullBytesThreshold == 0
                ? null
                : _connectionOptions.PullBytesThreshold,
            ForceLogicalMvccPull = _connectionOptions.ForceLogicalMvccPull,
            ExperimentalFeatures = string.IsNullOrWhiteSpace(_connectionOptions.SyncExperimentalFeatures)
                ? null
                : _connectionOptions.SyncExperimentalFeatures,
            HttpClient = SyncHttpClientFactory?.Invoke(),
        };
    }

    private void ValidateReplicaOptions()
    {
        if (_connectionOptions.Pooling)
            throw new NotSupportedException("Pooling is not supported for embedded replica connections yet. Set Pooling=False.");
        if (_connectionOptions.SyncInterval != 0)
            throw new NotSupportedException("Automatic sync is not supported for embedded replica connections yet. Set Sync Interval=0 and call SyncAsync explicitly.");
    }

    private void ValidateLocalOnlyOptions()
    {
        if (!string.IsNullOrWhiteSpace(_connectionOptions.AuthToken))
            throw new InvalidOperationException("Auth Token requires a remote Turso URL Data Source.");
        if (!string.IsNullOrWhiteSpace(_connectionOptions.ReplicaPath))
            throw new InvalidOperationException("Replica Path requires a remote Turso URL Data Source.");
        if (_connectionOptions.SyncInterval > 0)
            throw new InvalidOperationException("Sync Interval requires a remote embedded replica connection.");
        if (_connectionOptions.HasAdvancedReplicaOptions)
            throw new InvalidOperationException("Advanced sync options require a remote embedded replica connection.");
        if (_connectionOptions.Tls.HasValue)
            throw new InvalidOperationException("Tls requires a remote Turso URL Data Source.");
    }

    private void CloseRemote()
    {

View on GitHub (pinned to c1e5928725)

Solutions

Set 'Sync Interval=0' in the connection string.
Call SyncAsync() on the connection explicitly at the points where you need fresh remote data (e.g. on startup or on a timer you own).
If automatic sync is essential, use a driver/platform that supports it (e.g. the Rust SDK with sync interval) or wait for .NET support.

Example fix

// before
"Data Source=app.db;Replica Path=app.db;Sync Interval=60"
// after
"Data Source=app.db;Replica Path=app.db;Sync Interval=0"
// and drive it yourself:
await connection.SyncAsync();

Defensive patterns

Strategy: validation

Validate before calling

if (new TursoConnectionOptions(cs).SyncInterval != 0)
    throw new ArgumentException("Set Sync Interval=0 for embedded replicas and call SyncAsync explicitly.");

Prevention

Own your sync cadence: a CancellationToken-driven timer calling SyncAsync().
Document in team config that Sync Interval must be 0 for the .NET driver.

When it happens

Trigger: Opening an embedded replica connection (OpenReplica/OpenReplicaAsync) with 'Sync Interval' set to any value other than 0 in the connection string.

Common situations: Porting code that relied on automatic sync intervals in another SDK; copying a connection string that tuned sync frequency for an environment where this driver never had the feature.

Related errors

AI-assisted analysis of tursodatabase/turso@c1e5928725 (2026-08-31). Data as JSON: /api/errors/1112ff450d0f486e. Report an issue: GitHub.