tursodatabase/turso · error · NotSupportedException

Embedded replica connections are not supported yet by the .N

Error message

Embedded replica connections are not supported yet by the .NET provider. Use a remote URL without Replica Path for direct remote execution.

What it means

TursoConnection.Open() routes remote Data Sources to OpenRemote(), whose first guard rejects embedded-replica configuration with NotSupportedException because the .NET provider has not implemented replicas. IsReplica is true whenever the Data Source scheme is remote (libsql/http/https/ws/wss) and 'Replica Path' is non-empty — merely containing that keyword on a remote URL triggers the throw at Open().

Source

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

    internal void CloseRemoteSessionIfStateless()
    {
        if (_connectionOptions.ReadYourWrites || _remoteClient is not { HasOpenSession: true } remoteClient)
            return;

        try
        {
            remoteClient.CloseAsync(DefaultTimeout, CancellationToken.None).GetAwaiter().GetResult();
        }
        catch
        {
            InvalidateRemoteSession();
        }
    }

    private void OpenRemote()
    {
        if (_connectionOptions.IsReplica)
            throw new NotSupportedException("Embedded replica connections are not supported yet by the .NET provider. Use a remote URL without Replica Path for direct remote execution.");

        if (_connectionOptions.SyncInterval > 0)
            throw new NotSupportedException("Sync Interval requires embedded replica support, which is not supported yet by the .NET provider.");

        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.");

        _remoteClient = new TursoRemoteClient(_connectionOptions.GetRemoteUri(), _connectionOptions.AuthToken);
    }

    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.");

View on GitHub (pinned to 244cde92a7)

Solutions

  1. Remove 'Replica Path' from the connection string and use direct remote execution against the Turso URL
  2. If a local file database is wanted, use a plain file path Data Source with no remote-only keywords (Auth Token, Replica Path, Sync Interval, Tls)
  3. Track provider releases and move to replicas only once supported

Example fix

// before
var cs = "Data Source=libsql://my-db.turso.io;Auth Token=...;Replica Path=local.db";
using var conn = new TursoConnection(cs);
conn.Open(); // NotSupportedException

// after
var cs = "Data Source=libsql://my-db.turso.io;Auth Token=...";
using var conn = new TursoConnection(cs);
conn.Open();
Defensive patterns

Strategy: validation

Validate before calling

var opts = TursoConnectionOptions.Parse(cs);
if (opts.IsReplica)
    throw new InvalidOperationException(
        "Remove 'Replica Path': the .NET Turso provider only supports direct remote connections.");
using var conn = new TursoConnection(cs);
conn.Open();

Type guard

static bool IsSupportedConnectionString(string cs)
{
    var opts = TursoConnectionOptions.Parse(cs);
    return !opts.IsReplica && opts.SyncInterval <= 0;
}

Try / catch

try { conn.Open(); }
catch (NotSupportedException ex) when (ex.Message.Contains("Embedded replica connections are not supported"))
{
    // strip 'Replica Path' from config and retry with a direct remote URL
}

Prevention

When it happens

Trigger: Open() with 'Data Source=libsql://db.turso.io;Auth Token=...;Replica Path=local.db'; copying a replica connection string from Turso's Rust/Python/JS examples into a .NET app; environment config that adds Replica Path for offline scenarios.

Common situations: Polyglot repositories sharing one config file across languages; following Turso docs written for other bindings; app templates that include replica options by default; migrating from a wrapper that supported replicas.

Related errors

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