{"record":{"id":"faf56163c1256fec","repo":"tursodatabase/turso","slug":"sync-requires-an-embedded-replica-connection","errorCode":null,"errorMessage":"Sync requires an embedded replica connection.","messagePattern":"Sync requires an embedded replica connection\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"bindings/dotnet/src/Turso.Data/TursoConnection.cs","lineNumber":160,"sourceCode":"        command.CommandText = sql;\n\n        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        throw new NotSupportedException(\"Embedded replica sync is not supported yet by the .NET provider.\");\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    }","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/dotnet/src/Turso.Data/TursoConnection.cs#L142-L178","documentation":"SyncAsync only permits the sync code path for embedded-replica connections: IsReplica is true only when Data Source has a remote scheme (libsql/http/https/ws/wss) AND 'Replica Path' is non-empty. Any other open connection — a local file database or a direct remote connection without Replica Path — fails this guard with NotSupportedException before any work is done.","triggerScenarios":"conn.Sync() with Data Source pointing at a local file (app.db); conn.Sync() on a direct remote URL whose connection string lacks 'Replica Path=...'; reassigning ConnectionString to a non-replica value after opening.","commonSituations":"Code ported from Turso's Rust/Python/JS SDKs where sync is part of the workflow; assuming direct remote connections need a sync flush (they execute every statement server-side already); misspelling the 'Replica Path' keyword so it silently stays empty.","solutions":["Remove the Sync()/SyncAsync() call — with a direct remote connection (no Replica Path) every command already executes against the server, so there is nothing to flush","If you actually want an embedded replica, add 'Replica Path' to a remote connection string — but the .NET provider then throws 'Embedded replica sync is not supported yet' instead","Confirm Data Source is remote (libsql:// or https://); a local file connection can never sync"],"exampleFix":"// before\nvar cs = \"Data Source=libsql://db.turso.io;Auth Token=...\";\nusing var conn = new TursoConnection(cs);\nconn.Open();\nawait conn.SyncAsync(); // NotSupportedException: not a replica\n\n// after\nvar cs = \"Data Source=libsql://db.turso.io;Auth Token=...\";\nusing var conn = new TursoConnection(cs);\nconn.Open();\n// direct remote: statements already run on the server; drop the Sync call","handlingStrategy":"validation","validationCode":"var opts = TursoConnectionOptions.Parse(cs);\nif (opts.IsReplica)\n{\n    // .NET provider cannot sync replicas either (see NotSupportedException) -- do not call Sync\n}\nelse\n{\n    // direct remote or local: Sync is not applicable; every statement already executes remotely\n}","typeGuard":null,"tryCatchPattern":"try { await conn.SyncAsync(ct); }\ncatch (NotSupportedException) { /* sync not applicable to this connection mode */ }","preventionTips":["Only replica connections (remote URL plus Replica Path) pass the IsReplica check","Direct remote connections need no sync: statements execute server-side","Do not port Sync calls from Rust/Python/JS workflows without checking provider support"],"tags":["csharp","dotnet","turso","sync","embedded-replica","not-supported"],"backgroundTag":"sync-without-replica","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}