ClickHouse / ClickHouse/clickhouse-go

HTTP protocol: deterministic decode error while parsing exception block / EOF on first request every run, even with keep-alives disabled

Open
#1,916 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug needs triage
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/ping returns Ok. instantly and cleanly on cold start, every time.
  • Not a connection-pool reuse race — setting TransportFunc to force t.DisableKeepAlives = true does 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 mapping 18123:8123)
  • Interface: Protocol: clickhouse.HTTP via clickhouse.Open (not database/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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.