tursodatabase/turso · error · NotSupportedException

Turso batch execution requires a direct remote or embedded r

Error message

Turso batch execution requires a direct remote or embedded replica connection.

What it means

ExecuteBatch's sync-database path only supports connections that are a direct remote connection or an embedded replica. If the connection's SyncDatabase is null (neither case), the batch cannot be executed and NotSupportedException is thrown.

Source

Thrown at bindings/dotnet/src/Turso.Data/TursoBatch.cs:160

        return await CreateDataReaderAsync(results, behavior, cancellationToken).ConfigureAwait(false);
    }

    private async Task<IReadOnlyList<RemoteStatementResult>> ExecuteBatch(
        bool wantRows,
        CancellationToken cancellationToken)
    {
        cancellationToken.ThrowIfCancellationRequested();

        var connection = ValidateBatch();
        if (connection.IsRemote)
        {
            return await connection
                .ExecuteRemoteBatchAsync(_batchCommands.AsReadOnly(), Timeout, wantRows, cancellationToken)
                .ConfigureAwait(false);
        }

        if (connection.SyncDatabase is null)
            throw new NotSupportedException("Turso batch execution requires a direct remote or embedded replica connection.");

        var results = new List<RemoteStatementResult>(_batchCommands.Count);
        foreach (var batchCommand in _batchCommands.AsReadOnly())
        {
            cancellationToken.ThrowIfCancellationRequested();
            using var command = new TursoCommand(connection)
            {
                CommandText = batchCommand.CommandText,
                CommandTimeout = Timeout,
                Transaction = _transaction,
            };
            foreach (TursoParameter parameter in batchCommand.Parameters)
                command.Parameters.Add(parameter);

            results.Add(wantRows
                ? await BufferResultAsync(command, cancellationToken).ConfigureAwait(false)
                : new RemoteStatementResult
                {

View on GitHub (pinned to 6c72522679)

Solutions

1. Open the connection as a direct remote connection or embedded replica (configure TursoConnectionOptions with sync settings).
2. Check connection type before batching: fall back to sequential TursoCommand executions when SyncDatabase is null.
3. Catch NotSupportedException and surface a configuration error to the caller.

Example fix

// before
using var conn = new TursoConnection("file:local.db"); // no sync configured
await batch.ExecuteNonQueryAsync();
// after
var conn = new TursoConnection(new TursoConnectionStringBuilder { RemoteUrl = "...", AuthToken = "..." }.ToString());
await conn.OpenAsync();
await batch.ExecuteNonQueryAsync();

if (connection.SyncDatabase is null)
    throw new InvalidOperationException("Batches require a direct remote or embedded replica connection.");

try { await batch.ExecuteNonQueryAsync(ct); }
catch (NotSupportedException ex) when (ex.Message.Contains("Turso batch execution requires"))
{ /* fall back to sequential commands */ }

When it happens

Trigger: Calling TursoBatch.ExecuteNonQueryAsync/ExecuteReaderAsync (or the DbBatch API) on a TursoConnection that is neither a direct remote nor an embedded replica connection — e.g. a plain local file connection or one whose sync database was not configured.

Common situations: Configuring a connection without TursoConnectionOptions sync settings and then trying TursoBatch; running the same batch code against both sync-enabled and non-sync connections; forgetting to set up the embedded replica.

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

• Sync Interval must be between 0 and {MaximumSyncIntervalSeco
• Auth Token requires a remote Turso URL Data Source.
• invalid config: url is required
• Keyword not supported: {keyword}.
• Sync requires an embedded replica connection.

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