{"record":{"id":"8c6249e2c78bc710","repo":"tursodatabase/turso","slug":"sqlite-native-handles-are-not-available-for-direct","errorCode":null,"errorMessage":"SQLite native handles are not available for direct remote connections.","messagePattern":"SQLite native handles are not available for direct remote connections\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"bindings/dotnet/src/Turso.Data.Sqlite/SqliteConnection.cs","lineNumber":637,"sourceCode":"            {\n                NotifyManagedStateChange(originalState);\n            }\n        }\n\n        _disposed = true;\n        await base.DisposeAsync().ConfigureAwait(false);\n        failure?.Throw();\n    }\n\n    internal TursoDatabaseHandle DatabaseHandle\n    {\n        get\n        {\n            if (_managedConnection is not null)\n            {\n                if (IsReplica)\n                    return ManagedConnection.Turso;\n                throw new NotSupportedException(\n                    \"SQLite native handles are not available for direct remote connections.\");\n            }\n\n            return _database ?? throw new InvalidOperationException(\"The connection is not open.\");\n        }\n    }\n\n    internal bool HasOpenReader => _openReaderCount > 0;\n\n    internal bool IsReadOnly => _readOnly;\n\n    internal bool RecursiveTriggers => _recursiveTriggers;\n\n    internal bool ManagedReadYourWrites => _connectionOptions.ReadYourWrites;\n\n    internal void ReaderOpened() => _openReaderCount++;\n\n    internal void ReaderClosed()","sourceCodeStart":619,"sourceCodeEnd":655,"githubUrl":"https://github.com/tursodatabase/turso/blob/6c7252267988c76e632af00a671e4b9788dfae13/bindings/dotnet/src/Turso.Data.Sqlite/SqliteConnection.cs#L619-L655","documentation":"This NotSupportedException is thrown by the native-handle getter when the connection wraps a managed TursoConnection but is not an embedded replica. Direct remote connections have no local SQLite database handle to expose, so native-handle APIs cannot work.","triggerScenarios":"Accessing the connection's native handle property (e.g. Handle or an internal accessor used by extensions/interop) on a SqliteConnection wrapping a direct remote TursoConnection; the code path returns ManagedConnection.Turso only for replicas and otherwise throws.","commonSituations":"Interop code (e.g. sqlite3_* P/Invoke, backup, custom functions) written for local connections being applied to a direct remote wrapper; third-party libraries requesting the native handle generically.","solutions":["Use an embedded replica connection if you need native handles plus remote data","Perform the interop operation against a local SqliteConnection instead of a direct remote wrapper","Use the managed API surface (TursoConnection.Turso) directly for remote operations rather than native handles","Branch on IsManagedConnection/IsReplica before requesting the handle"],"exampleFix":"// before\nvar handle = remoteWrapper.Handle; // throws: direct remote\n\n// after\nif (remoteWrapper.IsManagedConnection && remoteWrapper.IsReplica)\n{\n    var turso = remoteWrapper.ManagedConnection.Turso;\n}","handlingStrategy":"type-guard","validationCode":"if (conn.IsManagedConnection && !conn.IsReplica) return UseManagedApi(conn);","typeGuard":"bool NativeHandleAvailable(SqliteConnection c) => !c.IsManagedConnection || c.IsReplica;","tryCatchPattern":"try { return conn.Handle; }\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"native handles\"))\n{\n    return null; // managed path only\n}","preventionTips":["Restrict native interop to local or embedded replica connections"],"tags":["dotnet","native-interop","remote-connection"],"backgroundTag":"unsupported-operation","analyzedSha":"6c7252267988c76e632af00a671e4b9788dfae13","analyzedAt":"2026-09-06T07:15:26.990Z","contentChangedAt":"2026-09-06T07:15:26.990Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}