tursodatabase/turso · error · InvalidOperationException

Advanced sync options require a remote embedded replica conn

Error message

Advanced sync options require a remote embedded replica connection.

What it means

Advanced replica sync options (partial sync, remote encryption, etc., exposed via HasAdvancedReplicaOptions) only make sense when connecting to a remote primary through an embedded replica. ValidateLocalOnlyOptions() throws InvalidOperationException during a plain Open() of a local or plain remote connection so these settings are not silently ignored.

Source

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

            Volatile.Write(ref _automaticSyncStatus, args.Status);
            generation = Volatile.Read(ref _automaticSyncGeneration);
            handlers = AutomaticSyncStatusChanged;
        }

        QueueAutomaticSyncStatusChanged(handlers, args.Status, generation);
    }

    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()
    {
        var remoteClient = _remoteClient;
        if (remoteClient is null)
            return;

        Exception? closeError = null;
        try
        {
            if (_remoteTransactionActive)
            {
                if (_remoteTransactionFailure is null)
                {
                    remoteClient

View on GitHub (pinned to 6c72522679)

Solutions

1. Remove the advanced sync options (partial sync / Remote Encryption) from the connection string.
2. If you actually want a replica, configure the data source as a remote Turso URL with 'Replica Path' so it opens as an embedded replica.
3. Split local and replica connection strings into separate configuration entries instead of sharing one.

Example fix

// before (local db with replica options)
"Data Source=local.db;Remote Encryption Cipher=aes-256-cbc;Remote Encryption Key=k"
// after
"Data Source=local.db"
// or make it a real replica:
"Data Source=https://mydb.turso.io;Replica Path=local.db;Remote Encryption Cipher=aes-256-cbc;Remote Encryption Key=k"

var opts = new TursoConnectionOptions(cs);
bool isReplica = !string.IsNullOrWhiteSpace(opts.ReplicaPath);
if (!isReplica && (opts.SyncInterval > 0 || opts.HasAdvancedReplicaOptions))
    throw new ArgumentException("Advanced sync options require an embedded replica connection string.");

When it happens

Trigger: Calling Open()/OpenAsync() on a non-replica connection (no remote URL + Replica Path setup) while the connection string includes advanced replica options such as Partial Sync settings or Remote Encryption, detected by HasAdvancedReplicaOptions.

Common situations: Leaving replica-related connection-string options in place after removing 'Replica Path' or switching the data source back to a plain local file; configuration shared across local and replica deployments.

Related errors

• Sync Interval requires an embedded replica connection.
• Advanced sync options require an embedded replica connection
• Replica Path requires a remote Turso URL Data Source.
• Sync Interval requires a remote embedded replica connection.
• 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/c292333bbfb54ceb. Report an issue: GitHub.