tursodatabase/turso · error · NotSupportedException

SQLite facade batches are available only for direct remote o

Error message

SQLite facade batches are available only for direct remote or embedded replica connections.

What it means

SQLite facade batches are only implemented for managed connections (direct remote or embedded replica connections). ValidateBatch checks connection.IsManagedConnection and throws NotSupportedException for any other connection kind, since the managed batch executor path does not exist for them.

Source

Thrown at bindings/dotnet/src/Turso.Data.Sqlite/SqliteBatch.cs:369

            }

            return new BatchState(managedBatch, statements, managedCommands, mappings);
        }
        catch
        {
            managedBatch.Dispose();
            throw;
        }
    }

    private SqliteConnection ValidateBatch()
    {
        var connection = _connection
                         ?? throw new InvalidOperationException(
                             "Connection must be set before executing a batch.");
        if (!connection.IsManagedConnection)
        {
            throw new NotSupportedException(
                "SQLite facade batches are available only for direct remote or embedded replica connections.");
        }
        if (connection.State != ConnectionState.Open)
            throw new InvalidOperationException(Properties.Resources.CallRequiresOpenConnection("ExecuteBatch"));
        if (_transaction is { IsCompleted: true })
            throw new InvalidOperationException(Properties.Resources.TransactionCompleted);
        if (_transaction is not null && !ReferenceEquals(_transaction.Connection, connection))
            throw new InvalidOperationException(Properties.Resources.TransactionConnectionMismatch);
        if (connection.Transaction is not null
            && !ReferenceEquals(_transaction, connection.Transaction))
        {
            throw new InvalidOperationException(Properties.Resources.TransactionRequired);
        }
        if (_batchCommands.Count == 0)
            throw new InvalidOperationException("Batch must contain at least one command.");

        return connection;
    }

View on GitHub (pinned to 6c72522679)

Solutions

1. Open the connection as a direct remote or embedded replica (managed) connection to use SqliteBatch
2. For local/embedded connections, execute statements with individual SqliteCommand calls or DbBatch alternatives supported by that path
3. Check connection.IsManagedConnection before choosing SqliteBatch

Example fix

// before
var localConn = new SqliteConnection("Data Source=local.db");
var batch = new SqliteBatch { Connection = localConn }; // NotSupportedException
// after
var remoteConn = SqliteConnection.CreateRemoteOrReplica(...); // managed connection
var batch = new SqliteBatch { Connection = remoteConn };

if (!connection.IsManagedConnection)
    throw new NotSupportedException("SqliteBatch requires a direct remote or embedded replica connection");

static bool SupportsBatches(SqliteConnection c) => c.IsManagedConnection;

try { await batch.ExecuteReaderAsync(); }
catch (NotSupportedException ex) when (ex.Message.Contains("SQLite facade batches")) { /* fall back to individual SqliteCommand execution */ }

When it happens

Trigger: Using SqliteBatch with a plain embedded/local (non-managed) SqliteConnection that doesn't route through the managed remote/replica machinery, then executing the batch.

Common situations: Assuming SqliteBatch works for every Turso connection type; local embedded file databases where SqliteBatch is unsupported; switching a connection factory from local to remote without updating batch usage.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Connection must be set before executing a batch.
• ExecuteBatch requires an open connection.
• Turso batch execution requires a direct remote or embedded r
• Turso batch execution is currently supported only for remote
• TursoBatchCommand only supports CommandType.Text.

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