tursodatabase/turso · error · TursoException

Unable to parse remote response: {ex.Message}

Error message

Unable to parse remote response: {ex.Message}

What it means

The HTTP call to /v2/pipeline returned a 2xx status, but the body could not be deserialized into the pipeline response envelope. System.Text.Json raised a JsonException, which TursoRemoteClient rethrows as a TursoException carrying the parser's message. The body is either not JSON at all (an HTML page, an empty string) or JSON whose shape does not match what the client expects (for example 'results' is not an array).

Source

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

        using var response = await _httpClient
            .SendAsync(httpRequest, HttpCompletionOption.ResponseHeadersRead, effectiveCancellationToken)
            .ConfigureAwait(false);

        var body = await response.Content.ReadAsStringAsync(effectiveCancellationToken).ConfigureAwait(false);
        if (!response.IsSuccessStatusCode)
        {
            throw new TursoException(
                $"Remote request failed with HTTP {(int)response.StatusCode} {response.ReasonPhrase}: {body}");
        }

        try
        {
            return JsonSerializer.Deserialize<RemotePipelineResponse>(body, JsonOptions)
                   ?? throw new TursoException("Remote request returned an empty response.");
        }
        catch (JsonException ex)
        {
            throw new TursoException($"Unable to parse remote response: {ex.Message}");
        }
    }

    private static CancellationTokenSource? CreateTimeout(int commandTimeout, CancellationToken cancellationToken)
    {
        if (commandTimeout <= 0)
            return null;

        var timeout = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        timeout.CancelAfter(TimeSpan.FromSeconds(commandTimeout));
        return timeout;
    }

    private static void ValidateAuthTokenTransport(Uri endpoint, string? authToken)
    {
        if (authToken is null
            || endpoint.Scheme.Equals(Uri.UriSchemeHttps, StringComparison.OrdinalIgnoreCase)
            || endpoint.IsLoopback)

View on GitHub (pinned to 244cde92a7)

Solutions

1. Reproduce the exact request with curl against <Url>/v2/pipeline and look at the raw body: HTML means a routing problem, partial JSON means truncation, complete-but-different JSON means schema drift.
2. If the body is HTML, fix routing so the Url reaches the database pipeline endpoint, not a web server.
3. If the body is truncated JSON, check proxies, response buffering, size limits, and timeouts between client and server.
4. If the body is well-formed but differently shaped, align the server version and the Turso.Data package version.
5. Log the failing SQL and endpoint when this fires so you can correlate with server-side logs.

try
{
    await using var reader = await cmd.ExecuteReaderAsync(cancellationToken);
}
catch (TursoException ex) when (ex.Message.StartsWith("Unable to parse remote response"))
{
    // 2xx + unparseable body: almost always routing/proxy, not data-dependent
    logger.LogError(ex, "Non-JSON body from {Url} while running {Sql}", url, cmd.CommandText);
    throw;
}

When it happens

Trigger: Any remote Execute/Batch/Close call through TursoConnection with a remote Url where the 200-status body is an HTML login or redirect page, an empty string (empty input is itself invalid JSON), a truncated stream, or a JSON document with unexpected field names or types.

Common situations: A reverse proxy or CDN returns an HTML error/interstitial page with status 200; an HTTP-to-HTTPS redirect body; the Url points at a web app or docs portal instead of the database; the response is truncated by a buffering proxy or a read timeout; the server version emits a response schema the installed Turso.Data bindings cannot parse.

Understand the failure class

Background: "Invalid JSON response" and "Failed to parse response" errors: when an API answers 200 but the body isn't the JSON your library expected — this error's family across 28 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Remote request returned an empty response.
• Remote response {Type} returned an empty result.
• Unable to parse remote {Type} response: {ex.Message}
• Remote request returned an empty ok response.
• Remote response {Type} did not include a result.

AI-assisted analysis of tursodatabase/turso@244cde92a7 (2026-08-20). Data as JSON: /api/errors/8ed85cbee3a40f06. Report an issue: GitHub.