Skip to content

chconn: take ClickHouse's error-code list from chtypes when it exposes one #661

Open

Description

@EricAndrechek

Area: chconn. This is conditional work; the trigger is below.

Now. internal/chconn/errclass.go classes a failed ClickHouse request with hand-kept maps of exception codes: unavailableCodes and deniedCodes, plus the tableScopedCodes and splittableCodes subsets. The code names exist only in comments. Any unlisted code is Rejected. ClickHouse publishes no retryable classification: src/Common/ErrorCodes.cpp is a flat code/name list, and the server's own retry decisions are separate lists wherever it retries. So some hand-kept list is unavoidable.

The risk is drift: a code a newer ClickHouse adds, or renumbers, silently lands as Rejected. SERVER_OVERLOADED (745) was missed exactly this way until #619.

Trigger: chtypes exposes ClickHouse's error codes. chtypes builds each artifact from the ClickHouse source of that version. If it starts exposing the exact code→name list for the version a line was built from, with or without a class per code, swap it in here:

  • replace the hand-kept names with chtypes' list;
  • add a unit test that every code chtypes lists for the pinned line has a class here. The test needs no ClickHouse container.

Until then (optional). An integration test against the pinned image would catch drift. It would run SELECT code, name FROM system.errors SETTINGS system_events_show_zero_values = 1, check the names of the codes we list, and diff the full code set against a checked-in snapshot. A newer image that adds codes would then fail with the list that needs classifying.

Also. Log the exception code and its name as structured fields (code, code_name) on the worker's outage and isolation log lines. Today the name only appears inside the error string, as the trailing (NAME) of the HTTP body.

Related: #619, and #403 / #271, where the query path will reuse Classify.

Activity

  1. EricAndrechek commented on Sep 26, 2026

    @EricAndrechek
    MemberAuthor

    Where to watch for this trigger: the fix is tracked upstream in chtypes, filed 2026-09-26. It will expose ClickHouse's own code → name table per line, taken from each line's own source. The mechanism is still open: a library function shipped with chtypes' next ABI revision, or a signed per-line data file served beside the goldens. Classification stays yours; a second, parked idea upstream would take a different approach but isn't planned. When the tracked item lands, it will say which form it took and where to read it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/ingestIngest pipeline (Bento, batching, DLQ)enhancementNew feature or request

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions