tursodatabase/turso · error · InvalidOperationException

The embedded replica is not initialized.

Error message

The embedded replica is not initialized.

What it means

TursoConnection.SyncAsync performs an embedded-replica sync (pull remote changes), which requires a _syncDatabase handle created when the connection is opened as a replica. If the connection is open, marked as a replica, but the sync handle was never initialized, SyncAsync throws this InvalidOperationException instead of dereferencing null.

Source

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

        return command.ExecuteNonQuery();
    }

    public void Sync()
    {
        SyncAsync(CancellationToken.None).GetAwaiter().GetResult();
    }

    public Task SyncAsync(CancellationToken cancellationToken = default)
    {
        ObjectDisposedException.ThrowIf(_disposed, this);
        if (cancellationToken.IsCancellationRequested)
            return Task.FromCanceled(cancellationToken);
        if (State != ConnectionState.Open)
            throw new InvalidOperationException("Turso database is closed.");
        if (!_connectionOptions.IsReplica)
            throw new NotSupportedException("Sync requires an embedded replica connection.");

        return (_syncDatabase ?? throw new InvalidOperationException("The embedded replica is not initialized."))
            .PullAsync(cancellationToken);
    }

    public override void ChangeDatabase(string databaseName)
    {
        throw new NotSupportedException("Turso does not support changing the active database.");
    }

    internal int DefaultTimeout => _connectionOptions.DefaultTimeout;

    internal bool IsRemote => _remoteClient is not null;

    internal bool ReadUncommitted
    {
        get => _readUncommitted;
        set => _readUncommitted = value;
    }

View on GitHub (pinned to 6c72522679)

Solutions

1. Reopen the connection so the replica (and its sync handle) is fully initialized before calling Sync.
2. Verify the connection string is the embedded-replica form (local file + remote Turso URL) and that Open succeeded via OpenReplica.
3. Ensure Sync is called only after the connection State is Open and replica bootstrap completed.
4. If the handle should exist, file a bug with the connection string shape (redacted) and open sequence.

Example fix

// before
using var conn = new TursoConnection(cs);
conn.Open();
await conn.SyncAsync(); // _syncDatabase may be null
// after
using var conn = new TursoConnection(replicaConnectionString);
await conn.OpenAsync();
if (conn.State != ConnectionState.Open) throw new InvalidOperationException("not open");
await conn.SyncAsync();

if (conn.State != ConnectionState.Open) throw new InvalidOperationException("open the connection first");
if (!conn.ConnectionString.Contains("Uri=turso://") || !conn.ConnectionString.Contains("Data Source=")) throw new InvalidOperationException("use embedded replica connection string");

try { await conn.SyncAsync(); } catch (InvalidOperationException ex) when (ex.Message.Contains("not initialized")) { /* reopen with replica connection string, then retry sync */ }

When it happens

Trigger: Calling Sync()/SyncAsync() on an embedded replica connection where _syncDatabase is null — e.g. the connection was opened before replica initialization completed, or the replica setup path was skipped while IsReplica was still true.

Common situations: Setting the embedded-replica connection string but opening with a code path that skips replica setup, mixing connection-string forms (remote vs local replica file), racing Sync before Open finishes replica bootstrap.

Related errors

• Automatic sync is not supported for embedded replica connect
• Sync requires an embedded replica connection.
• Embedded replica sync is not supported yet by the .NET provi
• Embedded replica connections are not supported yet by the .N
• Sync Interval requires embedded replica support, which is no

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