JDBC shows <Unreadable error message> (transport error: 200) for ClickHouse errors after upgrading to 26.3

[dramaturgerzn]

After upgrading ClickHouse from 25.9 to 26.3, JDBC clients started showing unreadable errors for any failed SQL query, using any DB tool (DBeaver, DataGrip, Pycharm).

ClickHouse version:

26.3.12.3-yc.1

Tested JDBC driver versions:

0.8.x
0.9.x

The behavior is the same with all tested versions.

Example query:

SELECT * FROM not_existing_table;

Expected error:

Code: 60. DB::Exception: Unknown table expression identifier 'not_existing_table' ...

Actual JDBC error:

SQL Error [60] [22000]: Code: 60. DB::Exception: <Unreadable error message> (transport error: 200)

The connection goes through chproxy.

With curl, the behavior depends on compress.

Without compress=1:

HTTP/2 404
Code: 60. DB::Exception: Unknown table expression identifier ...

With compress=1:

HTTP/2 200
content-length: 0
x-clickhouse-exception-code: 60
x-clickhouse-query-id: ...

So it looks like ClickHouse reports the error only via X-ClickHouse-Exception-Code, while the JDBC driver treats HTTP 200 as a successful response and then fails to read the error body.

This started only after upgrading ClickHouse from 25.9 to 26.3.

Expected behavior: if the response has X-ClickHouse-Exception-Code, the JDBC driver should treat it as a ClickHouse exception even when the HTTP status is 200, and should expose at least the exception code/query id instead of "Unreadable error message".

Possibly related: ClickHouse/clickhouse-go#1859

Different driver, but similar protocol-level behavior: HTTP 200 OK with X-ClickHouse-Exception-Code should still be treated as a ClickHouse query error.

[chernser]

Good day, @dramaturgerzn !

Thank you for reporting!
I think, it is already fixed by #2785

But I will test it anyway and will plan for work.

[chernser]

Triage Report

Size: Medium
Type: Bug
Affected Module: JDBC v2 / client-v2

Summary

When connecting to ClickHouse (or through chproxy) with compress=1, failing queries return an HTTP 200 response with content-length: 0 and the X-ClickHouse-Exception-Code header. The JDBC driver correctly detects the exception code from the header and throws a ServerException, but because the response body is empty, its error parser fails to extract a message and awkwardly falls back to emitting <Unreadable error message> (transport error: 200).

Recommended Labels & Priority

• Labels: bug, client-api-v2, area:network

Missing Information / Questions for User

1. Is this HTTP 200 + empty body on error behavior (with compress=1) specific to chproxy, or does ClickHouse 26.3 itself return an empty body when requested to compress an error response?
2. Since the server response body is genuinely empty (content-length: 0), what default exception message format would you prefer the driver to output instead of <Unreadable error message>? (e.g., "No error message provided by server").

Tests to Add

Test 1: Server returns HTTP 200 with Exception-Code header and empty body

@Test(groups = { "integration" })
public void testEmptyBodyExceptionWith200() {
    WireMockServer mockServer = new WireMockServer(WireMockConfiguration
            .options().port(9090).notifier(new ConsoleNotifier(false)));
    mockServer.start();

    try (Client client = new Client.Builder().addEndpoint(Protocol.HTTP, "localhost", mockServer.port(), false)
            .setUsername("default")
            .setPassword(ClickHouseServerForTest.getPassword())
            .build()) {
            
        mockServer.addStubMapping(WireMock.post(WireMock.anyUrl())
                .willReturn(WireMock.aResponse()
                        .withStatus(HttpStatus.SC_OK)
                        .withHeader("X-ClickHouse-Exception-Code", "60")
                        .withBody(""))); // Simulating content-length: 0

        try (QueryResponse response = client.query("SELECT * FROM not_existing_table").get(1, TimeUnit.SECONDS)) {
            Assert.fail("Expected exception");
        } catch (Exception e) {
            ServerException se = null;
            if (e instanceof ServerException) {
                se = (ServerException) e;
            } else if (e.getCause() instanceof ServerException) {
                se = (ServerException) e.getCause();
            } else {
                Assert.fail("Unexpected exception type", e);
            }
            
            Assert.assertEquals(se.getCode(), 60);
            Assert.assertFalse(se.getMessage().contains("<Unreadable error message>"));
            // Expected fallback message when body is empty
            Assert.assertTrue(se.getMessage().contains("No error message provided by server"));
        }
    } finally {
        mockServer.stop();
    }
}

[dramaturgerzn]

This is ClickHouse 26.3 behavior itself, not chproxy-specific. When compress=1 is set and a query fails, ClickHouse 26.3 returns HTTP 200 with content-length: 0 and the exception code only in the header. Without compress=1, it correctly returns HTTP 404 with plain text error body. Verified with direct curl requests bypassing chproxy.

[chernser]

Thank you, @dramaturgerzn !

[chernser]

@dramaturgerzn

I've added tests to verify the scenario #2869
Would you take a nightly build? - here some instructions https://gist.github.com/chernser/b4eacfde70093847449e3aef8e51ae8e

I've tested on latest CH version - there are another integration tests for that. They include cases with different compression and decompression.

Thanks!