tursodatabase/turso · error · InvalidOperationException

Replica Path requires a remote Turso URL Data Source.

Error message

Replica Path requires a remote Turso URL Data Source.

What it means

ValidateLocalOnlyOptions rejects 'Replica Path' on local connections: a replica path names the local file where an embedded replica of a remote database lives, so it only pairs with a remote Data Source. With a file path Data Source, Open() throws 'Replica Path requires a remote Turso URL Data Source.'

Source

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

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

View on GitHub (pinned to 244cde92a7)

Solutions

1. Remove 'Replica Path' for local databases
2. Or pair it with a remote Data Source — but note the .NET provider rejects replica connections entirely with NotSupportedException
3. When switching Data Source modes, clean all mode-specific keywords, not just the Data Source itself

Example fix

// before
var cs = "Data Source=app.db;Replica Path=replica.db"; // local + Replica Path

// after
var cs = "Data Source=app.db";

var opts = TursoConnectionOptions.Parse(cs);
if (!opts.IsRemote && !string.IsNullOrWhiteSpace(opts.ReplicaPath))
    throw new InvalidOperationException(
        "Remove 'Replica Path' or switch Data Source to a remote URL.");

static bool ReplicaPathMatchesMode(string cs)
{
    var opts = TursoConnectionOptions.Parse(cs);
    return opts.IsRemote || string.IsNullOrWhiteSpace(opts.ReplicaPath);
}

try { conn.Open(); }
catch (InvalidOperationException ex) when (ex.Message == "Replica Path requires a remote Turso URL Data Source.")
{
    // remove 'Replica Path' for local files; note replicas are unsupported in .NET even remotely
}

When it happens

Trigger: Open() with 'Data Source=app.db;Replica Path=replica.db' — two file paths, which is contradictory; leftover Replica Path keyword after changing the Data Source from a URL to a local file; config shared from replica-enabled environments.

Common situations: Switching an app between remote and local modes by editing only the Data Source; config copied from SDKs that support embedded replicas; template connection strings that include every option.

Related errors

• Sync Interval requires a remote embedded replica connection.
• Embedded replica connections are not supported yet by the .N
• Sync Interval requires embedded replica support, which is no
• Auth Token requires a remote Turso URL Data Source.
• Tls requires a remote Turso URL Data Source.

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