tursodatabase/turso · error · TursoException

Remote batch returned an unexpected result shape

Error message

Remote batch returned an unexpected result shape: {batch.StepResults.Count} results, {batch.StepErrors.Count} errors, expected {expectedCount}.

What it means

For a batch, the server must return exactly one step_results entry and one step_errors entry per submitted command. ExtractBatchStepResults threw because those arrays' lengths differ from the number of TursoBatchCommands sent, meaning the reply does not line up with the request.

Solutions

Log the batch size you submitted and the counts in the message (the exception text includes results, errors, and expected counts) to see which side is off.
Reproduce the batch pipeline POST with curl and count the step arrays in the raw JSON.
Align server and Turso.Data binding versions; batch shape changes are common across protocol revisions.
Remove truncating or transforming proxies from the path.
If the server intentionally changed shape, upgrade the bindings to the release that understands it.

Defensive patterns

Strategy: try-catch

Try / catch

try { return await batch.ExecuteReaderAsync(cancellationToken); }
catch (TursoException ex) when (ex.Message.Contains("unexpected result shape"))
{
    // message contains actual vs expected counts: log it verbatim
    logger.LogError(ex, "Batch step count mismatch for batch of {Count}", batch.BatchCommands.Count);
    throw;
}

Prevention

Keep the submitted command count and the observed counts from the message when reporting -- they identify the skew direction.
Version-align server and bindings; batch result semantics changed across protocol revisions.
Keep truncating proxies away from large batch responses.
Prefer many small batches over one huge batch to reduce blast radius and ease diagnosis.

When it happens

Trigger: TursoBatch execution on a remote connection where batch.step_results.Count or batch.step_errors.Count differs from commands.Count -- for example 3 commands submitted but 2 step results returned.

Common situations: Servers that deduplicate or collapse identical statements in a batch; response truncation by a proxy; version drift changing batch result semantics; custom servers returning a single aggregate result instead of per-step results.

Related errors

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

Appendix: source

Thrown at bindings/dotnet/src/Turso.Data/TursoRemoteClient.cs:306

        {
            case "ok":
                if (result.Response?.Type != "close")
                    throw new TursoException($"{operation} returned unexpected response type: {result.Response?.Type}");
                break;

            case "error":
                break;

            default:
                throw new TursoException($"{operation} returned unexpected result type: {result.Type}");
        }
    }

    private static List<RemoteStatementResult> ExtractBatchStepResults(RemoteBatchResult batch, int expectedCount)
    {
        if (batch.StepErrors.Count != expectedCount || batch.StepResults.Count != expectedCount)
        {
            throw new TursoException(
                $"Remote batch returned an unexpected result shape: {batch.StepResults.Count} results, {batch.StepErrors.Count} errors, expected {expectedCount}.");
        }

        for (var i = 0; i < batch.StepErrors.Count; i++)
        {
            if (batch.StepErrors[i] is { } error)
                throw CreateRemoteError(error);
        }

        var statementResults = new List<RemoteStatementResult>(expectedCount);
        for (var i = 0; i < batch.StepResults.Count; i++)
        {
            var stepResult = batch.StepResults[i]
                             ?? throw new TursoException($"Remote batch did not return a result for step {i}.");
            statementResults.Add(stepResult);
        }

        return statementResults;

View on GitHub (pinned to 6c72522679)