tursodatabase/turso · error · InvalidOperationException

Embedded replica '{path}' is already open with different opt

Error message

Embedded replica '{path}' is already open with different options.

What it means

The Turso .NET embedded replica registry tracks each open replica file with an options 'fingerprint'. When AcquireAsync is asked for a replica path that is already open with a different set of options (connection string/settings), it refuses to return a second handle because two incompatible configurations would fight over the same local replica. The caller must close the existing instance or reuse the same options.

Source

Thrown at bindings/dotnet/src/Turso.Data/TursoReplicaRegistry.cs:43

                .ConfigureAwait(false);
            return Lease.CreateStandalone(
                database,
                new TursoAutomaticSyncCoordinator(database, syncInterval, timeProvider));
        }

        var path = Path.GetFullPath(options.Path);
        var fingerprint = Fingerprint.Create(options, syncInterval);
        Entry entry;
        lock (Gate)
        {
            if (Entries.TryGetValue(path, out entry!))
            {
                if (entry.Closing)
                    throw new InvalidOperationException($"Embedded replica '{path}' is closing.");
                if (!pooling || !entry.Pooling)
                    throw new InvalidOperationException($"Embedded replica '{path}' is already open exclusively.");
                if (entry.Fingerprint != fingerprint)
                    throw new InvalidOperationException($"Embedded replica '{path}' is already open with different options.");

                checked
                {
                    entry.ReferenceCount++;
                }
            }
            else
            {
                entry = new Entry(path, pooling, fingerprint)
                {
                    ReferenceCount = 1,
                };
                entry.Initialization = InitializeAsync(entry, options, syncInterval, timeProvider);
                Entries.Add(path, entry);
            }
        }

        try

View on GitHub (pinned to 6c72522679)

Solutions

Reuse the exact same connection string/options for every connection that targets the same local replica path.
Find and dispose/close the existing connection that opened the replica with the old options before opening with new options.
Use a distinct local replica file path if you genuinely need different replica configurations.
Ensure connection string parameters are normalized (same order, no accidental differences) when constructing connections in different places.

Example fix

// before
var a = new TursoConnection("Data Source=rep.db;SyncUrl=https://x.turso.io");
var b = new TursoConnection("Data Source=rep.db;SyncUrl=https://x.turso.io;Pooling=true");

// after: identical options for the same replica path
var a = new TursoConnection("Data Source=rep.db;SyncUrl=https://x.turso.io;Pooling=true");
var b = new TursoConnection("Data Source=rep.db;SyncUrl=https://x.turso.io;Pooling=true");

Defensive patterns

Strategy: validation

Validate before calling

// Ensure options are identical for the same replica path before opening
var opts = "Data Source=rep.db;SyncUrl=https://x.turso.io;Pooling=true";
if (openReplicas.TryGetValue(replicaPath, out var existing) && existing.Options != opts)
    throw new InvalidOperationException("Replica already open with different options; reuse existing options or close it first.");

Try / catch

try
{
    await TursoReplicaRegistry.AcquireAsync(path, options);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("different options"))
{
    // close existing connection or normalize options and retry
}

Prevention

Centralize connection-string construction in one factory so all connections for a replica share identical options.
Keep a registry of open replica connections and reuse them instead of opening new ones.
Never mix pooling and non-pooling access to the same replica path.
Use one distinct local file per distinct replica configuration.

When it happens

Trigger: Calling TursoConnection with embedded replica (AcquireAsync) for a path already registered while passing a connection string or replica options that hash to a different fingerprint than the first opener (e.g. different sync interval, different remote URL, different flags like pooling).

Common situations: Opening two TursoConnection instances in the same process pointing at the same local replica file but built from differently ordered/different connection-string parameters; a long-lived singleton connection plus a second ad-hoc connection with tweaked options; mixing pooling and non-pooling usage.

Related errors

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