tursodatabase/turso · error · NotSupportedException

Advanced sync options require an embedded replica connection

Error message

Advanced sync options require an embedded replica connection.

What it means

Advanced replica options (beyond basic SyncInterval) only make sense for an embedded replica that performs local syncs. OpenRemote rejects them when the data source is a remote Turso URL because there is no local replica to apply them to.

Source

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

        }
        catch
        {
            InvalidateRemoteSession();
        }
    }

    private void OpenRemote()
    {
        if (_connectionOptions.IsReplica)
        {
            OpenReplica();
            return;
        }

        if (_connectionOptions.SyncInterval > 0)
            throw new NotSupportedException("Sync Interval requires an embedded replica connection.");
        if (_connectionOptions.HasAdvancedReplicaOptions)
            throw new NotSupportedException("Advanced sync options require an embedded replica connection.");

        if (_connectionOptions.GetEncryptionCipher().HasValue || !string.IsNullOrWhiteSpace(_connectionOptions["Encryption Key"]))
            throw new InvalidOperationException("Encryption Cipher and Encryption Key are local database options and cannot be used with remote Turso URLs.");

        var handler = RemoteMessageHandlerFactory?.Invoke();
        _remoteClient = handler is null
            ? new TursoRemoteClient(_connectionOptions.GetRemoteUri(), _connectionOptions.AuthToken)
            : new TursoRemoteClient(
                new HttpClient(handler),
                _connectionOptions.GetRemoteUri(),
                _connectionOptions.AuthToken,
                disposeHttpClient: true);
    }

    private void OpenReplica()
    {
        var lease = TursoReplicaRegistry
            .AcquireAsync(

View on GitHub (pinned to 6c72522679)

Solutions

1. Remove the advanced replica options from the remote connection string.
2. Use the full embedded-replica connection string (local file + remote Uri) if those options are needed.
3. Move advanced option setup behind a check on connection type so they are only applied to replica connections.

Example fix

// before
var cs = "Data Source=turso://mydb-myorg.turso.io;SyncInterval=60;AdvancedSync=...";
// after
var cs = "Data Source=turso://mydb-myorg.turso.io;"; // remote only
// or keep advanced options with:
var cs = "Data Source=/local/replica.db;Uri=turso://mydb-myorg.turso.io;SyncInterval=60;AdvancedSync=...";

var b = new DbConnectionStringBuilder { ConnectionString = cs };
bool isRemote = (b["Data Source"] as string ?? "").StartsWith("turso://");
bool hasAdvanced = /* any advanced replica keys present */ b.Keys.Cast<string>().Any(k => k.StartsWith("Sync") && k != "SyncInterval");
if (isRemote && hasAdvanced) throw new NotSupportedException("advanced replica options need a local replica");

try { conn.Open(); } catch (NotSupportedException ex) when (ex.Message.Contains("Advanced sync options")) { /* remove advanced options or use embedded replica cs */ }

When it happens

Trigger: Opening a TursoConnection with a remote URL while setting advanced replica options in the connection string (HasAdvancedReplicaOptions is true, e.g. sync-related tuning flags).

Common situations: Copy-pasting an embedded-replica connection string but changing the data source to a remote URL, enabling advanced sync settings globally and opening a remote-only connection, refactoring connection setup without cleaning up replica options.

Related errors

• Sync Interval requires an embedded replica connection.
• Replica Path requires a remote Turso URL Data Source.
• Sync Interval requires a remote embedded replica connection.
• Advanced sync options require a remote embedded replica conn
• Embedded replica connections are not supported yet by the .N

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