tursodatabase/turso · error · InvalidOperationException

The connection does not use the managed Turso backend.

Error message

The connection does not use the managed Turso backend.

What it means

This InvalidOperationException is thrown by the internal ManagedConnection property when accessed on a SqliteConnection whose _managedConnection field is null, i.e. a connection that is not backed by the managed Turso backend (native local connections and replicas without a managed wrapper).

Source

Thrown at bindings/dotnet/src/Turso.Data.Sqlite/SqliteConnection.cs:125

    public bool IsDirectRemote => _connectionOptions.IsDirectRemote;

    public bool IsRemote => _connectionOptions.IsRemote;

    public bool IsReplica => _connectionOptions.IsReplica;

    public bool IsManaged => IsRemote;

    public TursoSyncDatabase? SyncDatabase => _managedConnection?.SyncDatabase;

    internal bool IsSharedCache => _connectionOptions.Cache == SqliteCacheMode.Shared;

    internal bool IsManagedConnection => _managedConnection is not null;

    private bool HasNativeCallbackHandle =>
        _database is not null || IsReplica && State == ConnectionState.Open;

    internal TursoConnection ManagedConnection => _managedConnection
        ?? throw new InvalidOperationException("The connection does not use the managed Turso backend.");

    internal bool ReadUncommitted
    {
        get => _readUncommitted;
        set => _readUncommitted = value;
    }

    // The SQLite version Turso tracks (SQLITE_VERSION in core/dialect/sqlite.rs).
    public override string ServerVersion => "3.50.4";

    public override ConnectionState State => _managedConnection?.State
        ?? (_database is null ? ConnectionState.Closed : ConnectionState.Open);

    public override bool CanCreateBatch => _managedConnection?.CanCreateBatch == true;

    protected override DbProviderFactory DbProviderFactory => SqliteFactory.Instance;

    public override void Open()

View on GitHub (pinned to 6c72522679)

Solutions

1. Check conn.IsManagedConnection before accessing ManagedConnection
2. Use the wrapper constructor SqliteConnection(TursoConnection, bool) to obtain a managed-backed connection
3. Route local connections through the native code path instead of managed APIs

Example fix

// before
var turso = conn.ManagedConnection.Turso; // throws for local conns

// after
if (conn.IsManagedConnection)
{
    var turso = conn.ManagedConnection.Turso;
}

if (!conn.IsManagedConnection) return UseNativePath(conn);

bool IsManaged(SqliteConnection c) => c.IsManagedConnection;

try { UseManaged(conn.ManagedConnection); }
catch (InvalidOperationException ex) when (ex.Message.Contains("managed Turso backend"))
{
    UseNativePath(conn);
}

When it happens

Trigger: Invoking internal APIs that require the managed backend (e.g. managed statements, Turso handle access on non-replica wrappers, batch operations) on a SqliteConnection created purely from a local connection string.

Common situations: Internal/extension code calling ManagedConnection without first checking IsManagedConnection; tests or tooling mixing native and managed connection objects.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• invalid config: url is required
• Connection must be a TursoConnection.
• Connection must be set before executing a command.
• Connection must be set before preparing a command.
• Connection must be a SqliteConnection.

AI-assisted analysis of tursodatabase/turso@6c72522679 (2026-09-06). Data as JSON: /api/errors/43b310b9011878c8. Report an issue: GitHub.