{"record":{"id":"7e3cb56671719b1e","repo":"tursodatabase/turso","slug":"turso-native-call-failed-with-status-status","errorCode":null,"errorMessage":"Turso native call failed with status {status}.","messagePattern":"Turso native call failed with status (.+?)\\.","errorType":"exception","errorClass":"TursoException","httpStatus":null,"severity":"error","filePath":"bindings/dotnet/src/Turso.Raw/Public/TursoBindings.cs","lineNumber":433,"sourceCode":"        {\n            var data = new ReadOnlySpan<byte>((void*)ptr, checked((int)length));\n            return data.ToArray();\n        }\n    }\n\n    private static UIntPtr ToNativeIndex(int index) => checked((UIntPtr)(ulong)index);\n\n    private static UIntPtr ToNativeLength(int length) => checked((UIntPtr)(ulong)length);\n\n    private static void ThrowIfError(TursoStatusCode status, IntPtr errorPtr, string? messagePrefix = null)\n    {\n        if (errorPtr != IntPtr.Zero)\n            ThrowException(errorPtr, messagePrefix);\n\n        if (status is TursoStatusCode.Ok or TursoStatusCode.Done or TursoStatusCode.Row)\n            return;\n\n        throw new TursoException($\"Turso native call failed with status {status}.\");\n    }\n\n    private static void ThrowException(IntPtr errorPtr, string? messagePrefix = null)\n    {\n        var errorMessage = Marshal.PtrToStringUTF8(errorPtr);\n        var exception = new TursoException($\"{messagePrefix}{errorMessage ?? \"Internal error\"}\");\n        TursoInterop.FreeString(errorPtr);\n        throw exception;\n    }\n\n    private sealed class NativeUtf8String : IDisposable\n    {\n        private NativeUtf8String(IntPtr pointer) => Pointer = pointer;\n\n        public IntPtr Pointer { get; private set; }\n\n        public static NativeUtf8String From(string? value)\n        {","sourceCodeStart":415,"sourceCodeEnd":451,"githubUrl":"https://github.com/tursodatabase/turso/blob/6c7252267988c76e632af00a671e4b9788dfae13/bindings/dotnet/src/Turso.Raw/Public/TursoBindings.cs#L415-L451","documentation":"ThrowIfError is the shared exit check for all native P/Invoke calls in TursoBindings: statuses Ok/Done/Row pass, an error-string pointer produces a native message, and everything else throws TursoException carrying the raw status enum name (e.g. Busy, Io, Interrupt). This variant appears when native code fails without returning an error string, so the status code is all the diagnostics you get.","triggerScenarios":"Any wrapped native operation failing silently: opening a database file you cannot read/write (Io), a locked/busy database during write contention (Busy), interrupted execution, out-of-memory conditions, or an unrecognized status from a version-mismatched native library.","commonSituations":"Concurrent writers on the same file causing busy failures; wrong file permissions or a read-only mount; disk full; container memory limits; partial upgrades where the native library returns statuses the bindings do not map.","solutions":["Read the status name from the message to classify: Busy -> retry after backoff; Io -> check path, permissions, disk; Interrupt/Oom -> inspect app state and resources.","For Busy, wrap statements in a bounded retry with exponential backoff and consider a busy timeout if the layer exposes one.","Verify the database path is readable/writable and the volume has space.","Ensure the native library shipped with the bindings version you reference (no partial upgrades)."],"exampleFix":"// before\nvar stmt = TursoBindings.PrepareStatement(db, sql); // may throw: Turso native call failed with status Busy.\n\n// after\nTursoStatementHandle stmt;\nfor (var attempt = 0; ; attempt++)\n{\n    try { stmt = TursoBindings.PrepareStatement(db, sql); break; }\n    catch (TursoException ex) when (attempt < 3 && ex.Message.Contains(\"Busy\"))\n    {\n        Thread.Sleep(100 << attempt);\n    }\n}","handlingStrategy":"try-catch","validationCode":"// pre-flight the conditions behind the common statuses\nif (!File.Exists(path)) throw new FileNotFoundException(path);\nif (!HasWriteAccess(Path.GetDirectoryName(path))) throw new UnauthorizedAccessException(path);","typeGuard":null,"tryCatchPattern":"catch (TursoException ex)\n{\n    if (ex.Message.Contains(\"Busy\") && attempt < maxRetries) { await Task.Delay(backoff); continue; }\n    if (ex.Message.Contains(\"Io\")) { /* verify path, permissions, disk space; do not retry blindly */ }\n    throw;\n}","preventionTips":["Check file existence and write permissions before opening local databases.","Serialize writers or use a single writer connection to avoid Busy storms.","Retry only transient statuses (Busy, Io) with bounded exponential backoff.","Upgrade native library and bindings together as one unit."],"tags":["dotnet","native-interop","status-code","busy","io-error"],"backgroundTag":"native-library-call-failed","analyzedSha":"6c7252267988c76e632af00a671e4b9788dfae13","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}