ClickHouse / ClickHouse/clickhouse-go
HTTP protocol: deterministic decode error while parsing exception block / EOF on first request every run, even with keep-alives disabled
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 3.3k
- Forks
- 684
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 14
Description
Observed the bug
Every single clickhouse.Open() + Ping() call using Protocol: clickhouse.HTTP fails its first internal query (SELECT displayName(), version(), revision(), timezone()) with a decode error while parsing exception block / read: EOF error. The driver's internal retry then opens a second connection which succeeds immediately. This is 100% reproducible on every process start — not intermittent.
To reproduce
conn, err := clickhouse.Open(&clickhouse.Options{
Addr: []string{"127.0.0.1:18123"},
Protocol: clickhouse.HTTP,
Auth: clickhouse.Auth{
Database: "default",
Username: "default",
Password: "<password>",
},
Logger: slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug})),
})
if err != nil {
return nil, err
}
err = conn.Ping(context.Background())
Observed log output
{"level":"DEBUG","msg":"querying server info via HTTP","conn_id":1,"remote_addr":"127.0.0.1:18123","protocol":"http"}
{"level":"DEBUG","msg":"HTTP query","conn_id":1,"sql":"SELECT displayName(), version(), revision(), timezone()"}
{"level":"ERROR","msg":"HTTP read data: decode error while parsing exception block","conn_id":1,"error":"read: read: EOF"}
{"level":"DEBUG","msg":"new connection established","conn_id":1,"protocol":"http"}
{"level":"DEBUG","msg":"ping","conn_id":1,"protocol":"http"}
{"level":"DEBUG","msg":"HTTP query","conn_id":1,"sql":"SELECT 1"}
{"level":"ERROR","msg":"HTTP read data: decode error while parsing exception block","conn_id":1,"error":"read: read: EOF"}
{"level":"DEBUG","msg":"connection released to pool","conn_id":1,"protocol":"http"}
conn.Ping() ultimately returns nil and the connection works normally afterward — but the error is logged on literally every process start.
What I've ruled out
- Not a Docker/network issue —
curl -s http://127.0.0.1:18123/pingreturnsOk.instantly and cleanly on cold start, every time. - Not a connection-pool reuse race — setting
TransportFuncto forcet.DisableKeepAlives = truedoes not change the behavior; error is byte-for-byte identical. - Not container warmup — ClickHouse container had been running for 20+ hours with no other traffic when this was reproduced.
- Switching
Protocol: clickhouse.Native(port 9000) connects cleanly with zero errors on every run, confirming the server itself is healthy.
Environment
- clickhouse-go version: v2.47.0
- Go version: 1.26.5
- OS: darwin (macOS)
- ClickHouse server version: 26.6.1 (Docker image
clickhouse/clickhouse-server, port mapping18123:8123) - Interface:
Protocol: clickhouse.HTTPviaclickhouse.Open(notdatabase/sql)
Expected behavior
The first HTTP request per connection should succeed without an internal retry, matching the behavior of curl and the native protocol.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with clickhouse.Open and Ping using the provided HTTP reproduction, then trace the internal server-info query and the HTTP read-data path that reports the exception-block decode error. Compare the first request with the retry and native protocol behavior; done means the first HTTP request succeeds without the logged EOF/decode error and the reproduction passes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- backend, databases
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100