{"record":{"id":"8d51cac91337a606","repo":"tursodatabase/turso","slug":"turso-sync-operation-failed-message","errorCode":null,"errorMessage":"Turso sync ${operation} failed: ${message}","messagePattern":"Turso sync (.+?) failed: (.+?)","errorType":"exception","errorClass":"TursoSyncException","httpStatus":null,"severity":"error","filePath":"bindings/dotnet/src/Turso.Data/TursoSyncDatabase.cs","lineNumber":382,"sourceCode":"        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)\n        {\n            try\n            {\n                CancelQueuedIo();\n            }\n            catch\n            {\n                // Preserve cancellation after making the best effort to release native callbacks.\n            }\n            throw;\n        }\n        catch (TursoSyncException)\n        {\n            throw;\n        }\n        catch (Exception exception)\n        {\n            throw CreateSyncException(operationKind, exception);\n        }\n    }\n\n    private TursoSyncOperationHandle StartOperation(\n        Func<TursoSyncDatabaseHandle, TursoSyncOperationHandle> start,\n        TursoSyncOperationKind operationKind)\n    {\n        _lastTransportContext = null;\n        try\n        {\n            return start(_handle);\n        }\n        catch (TursoSyncException)\n        {\n            throw;\n        }\n        catch (Exception exception)\n        {","sourceCodeStart":364,"sourceCodeEnd":400,"githubUrl":"https://github.com/tursodatabase/turso/blob/6c7252267988c76e632af00a671e4b9788dfae13/bindings/dotnet/src/Turso.Data/TursoSyncDatabase.cs#L364-L400","documentation":"DriveOperationAsync pumps a native Turso sync operation to completion; when any unexpected exception escapes the resume/IO loop (other than TursoSyncException or cancellation), it is wrapped via CreateSyncException into 'Turso sync <operation> failed: <message>' with the operation kind (pull, stats, connect, etc.). It signals that the sync operation could not complete, with the inner exception carrying the root cause.","triggerScenarios":"Calling PullAsync, GetStatsAsync, ConnectHandleAsync, or a void sync operation when the underlying native binding or IO queue throws a non-TursoSyncException: invalid handle/state, IO callbacks failing, or an unexpected InvalidOperationException (e.g. unknown operation state).","commonSituations":"Disposing the TursoSyncDatabase while a pull is in flight; native library load problems; transport/IO handler throwing during ProcessIoQueueAsync; race conditions around the handle from another thread.","solutions":["Read the InnerException of the TursoSyncException to find the root cause and fix that (network, file, or state issue).","Ensure the database handle is not disposed or used concurrently while sync operations run.","Retry the operation; transient IO/network failures during pull are common.","Catch TursoSyncException specifically around sync calls and apply backoff/reconnect logic."],"exampleFix":"// before\nawait db.PullAsync(); // raw, crashes on unexpected failure\n// after\ntry { await db.PullAsync(); }\ncatch (TursoSyncException ex) { log(ex.Message, ex.InnerException); await ReconnectAndRetry(db); }","handlingStrategy":"try-catch","validationCode":"if (db.IsDisposed) throw new InvalidOperationException(\"TursoSyncDatabase disposed before sync\");\nObjectDisposedException.ThrowIf(!_handle.IsInvalid, _handle);","typeGuard":"static bool HasRootCause(TursoSyncException ex, Type t) =>\n    ex.InnerException is not null && t.IsInstanceOfType(ex.InnerException);","tryCatchPattern":"try { await db.PullAsync(token); }\ncatch (TursoSyncException ex) when (ex.InnerException is IOException or ObjectDisposedException) {\n    logger.LogWarning(ex, \"sync pull failed: {Msg}\", ex.Message);\n    await Task.Delay(TimeSpan.FromSeconds(2), token);\n}","preventionTips":["Always catch TursoSyncException around sync calls and log InnerException","Do not dispose the database while sync operations are in flight","Serialize sync operations; avoid concurrent PullAsync/ApplyOperation on one handle","Retry transient failures with exponential backoff"],"tags":["csharp","dotnet","sync","native-interop"],"backgroundTag":"sync-operation-failed","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"}