{"record":{"id":"9a1f0d05acf29de9","repo":"tursodatabase/turso","slug":"the-embedded-replica-is-not-initialized","errorCode":null,"errorMessage":"The embedded replica is not initialized.","messagePattern":"The embedded replica is not initialized\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"bindings/dotnet/src/Turso.Data/TursoConnection.cs","lineNumber":205,"sourceCode":"        return command.ExecuteNonQuery();\n    }\n\n    public void Sync()\n    {\n        SyncAsync(CancellationToken.None).GetAwaiter().GetResult();\n    }\n\n    public Task SyncAsync(CancellationToken cancellationToken = default)\n    {\n        ObjectDisposedException.ThrowIf(_disposed, this);\n        if (cancellationToken.IsCancellationRequested)\n            return Task.FromCanceled(cancellationToken);\n        if (State != ConnectionState.Open)\n            throw new InvalidOperationException(\"Turso database is closed.\");\n        if (!_connectionOptions.IsReplica)\n            throw new NotSupportedException(\"Sync requires an embedded replica connection.\");\n\n        return (_syncDatabase ?? throw new InvalidOperationException(\"The embedded replica is not initialized.\"))\n            .PullAsync(cancellationToken);\n    }\n\n    public override void ChangeDatabase(string databaseName)\n    {\n        throw new NotSupportedException(\"Turso does not support changing the active database.\");\n    }\n\n    internal int DefaultTimeout => _connectionOptions.DefaultTimeout;\n\n    internal bool IsRemote => _remoteClient is not null;\n\n    internal bool ReadUncommitted\n    {\n        get => _readUncommitted;\n        set => _readUncommitted = value;\n    }\n","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/tursodatabase/turso/blob/6c7252267988c76e632af00a671e4b9788dfae13/bindings/dotnet/src/Turso.Data/TursoConnection.cs#L187-L223","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reopen the connection so the replica (and its sync handle) is fully initialized before calling Sync.","Verify the connection string is the embedded-replica form (local file + remote Turso URL) and that Open succeeded via OpenReplica.","Ensure Sync is called only after the connection State is Open and replica bootstrap completed.","If the handle should exist, file a bug with the connection string shape (redacted) and open sequence."],"exampleFix":"// before\nusing var conn = new TursoConnection(cs);\nconn.Open();\nawait conn.SyncAsync(); // _syncDatabase may be null\n// after\nusing var conn = new TursoConnection(replicaConnectionString);\nawait conn.OpenAsync();\nif (conn.State != ConnectionState.Open) throw new InvalidOperationException(\"not open\");\nawait conn.SyncAsync();","handlingStrategy":"validation","validationCode":"if (conn.State != ConnectionState.Open) throw new InvalidOperationException(\"open the connection first\");\nif (!conn.ConnectionString.Contains(\"Uri=turso://\") || !conn.ConnectionString.Contains(\"Data Source=\")) throw new InvalidOperationException(\"use embedded replica connection string\");","typeGuard":null,"tryCatchPattern":"try { await conn.SyncAsync(); } catch (InvalidOperationException ex) when (ex.Message.Contains(\"not initialized\")) { /* reopen with replica connection string, then retry sync */ }","preventionTips":["Always await OpenAsync()/Open() completing before Sync.","Use one helper to build embedded-replica connection strings.","Confirm the replica file exists and is a valid replica after reopening."],"tags":["dotnet","embedded-replica","sync","state-error"],"backgroundTag":"replica-not-initialized","analyzedSha":"6c7252267988c76e632af00a671e4b9788dfae13","analyzedAt":"2026-08-31T11:17:35.598Z","contentChangedAt":"2026-08-31T11:17:35.598Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}