ClickHouse Version Compatibility#

Overview#

Langfuse manages ClickHouse version compatibility through three mechanisms: (1) automatic version detection at startup that injects per-query optimizer settings, (2) manual environment variable overrides, and (3) image version pinning in compose files. The root problem is ClickHouse's experimental query analyzer (enable_analyzer=1), which became default in 25.x/26.x and breaks several of Langfuse's query patterns.

The Root Problem: Analyzer Behavior Changes#

ClickHouse's new query analyzer (enabled by default from ~25.x/26.x) causes two distinct failure modes in Langfuse:

1. NOT_FOUND_COLUMN_IN_BLOCK errors — The analyzer incorrectly transforms AND keyword conditions into internal and(...) function-call identifiers when FINAL + LEFT JOIN are combined. This breaks the Scores and Observations queries, manifesting as 500 errors on the scores page and the scores.all API. 1 2

2. CAST AS Map type mismatches — The traces.metrics query using ORDER BY ... LIMIT 1 BY id, project_id for deduplication triggers a type-inference bug in the analyzer, causing failures with Unsupported types to CAST AS Map errors after upgrading to ClickHouse 25.12. 3

The query_plan_optimize_lazy_materialization optimizer is the proximate cause — enabled by default from ClickHouse 25.4.0 onward, it interacts badly with specific query shapes Langfuse uses. 4

Automatic Version Detection (Primary Mitigation)#

PR #14187 introduced compatibility.ts — the central module for version-aware ClickHouse configuration. 4

How it works:

1. At startup, initializeClickhouseCompatibility() runs SELECT version() against ClickHouse. 5
2. The returned version string is parsed and evaluated against CLICKHOUSE_COMPATIBILITY_RULES. 5
3. Currently, the single defined rule is disable-lazy-materialization: for versions ≥ 25.4.0, it injects query_plan_optimize_lazy_materialization: 0 into every client connection's clickhouse_settings. 5
4. The detected version and computed flags are logged via resolveClickHouseCompatibility() for observability — including whether each rule matched and was applied. 6

The result is cached module-level in detectedClickHouseVersion so version detection runs only once per process lifetime. 5

This initialization runs before the application accepts requests in both web (web/src/initialize.ts) and worker (worker/src/index.ts) entry points. 4

Environment Variable Control#

The behavior is governed by CLICKHOUSE_DISABLE_LAZY_MATERIALIZATION (defined in packages/shared/src/server/clickhouse/compatibility.ts): 5

Setting CLICKHOUSE_DISABLE_LAZY_MATERIALIZATION=true is the recommended manual workaround for self-hosters running ClickHouse 25.x/26.x before upgrading Langfuse to a version with auto-detection. 1 2

Version Pinning#

PR #14563 pinned the docker-compose.yml ClickHouse image to clickhouse-server:24.3 as a short-term safeguard to prevent users from accidentally pulling ClickHouse 26.x. 7 The snapshot of docker-compose.yml at commit 471e150a shows the image still unpinned (docker.io/clickhouse/clickhouse-server with no tag) 8 — check the current main branch file for the latest state.

CI Test Matrix#

PR #14066 established a three-way version matrix in CI to catch version regressions proactively: 9

• 24.3 — minimum supported baseline (docker-compose.dev-azure.yml)
• 25.12 — current Langfuse Cloud version (docker-compose.dev.yml)
• 26.6 — latest release (docker-compose.dev-redis-cluster.yml), requiring CLICKHOUSE_DISABLE_LAZY_MATERIALIZATION=true

Known Limitations#

• Cluster/Distributed tables: The automatic compatibility detection does not fully resolve issues on ClickHouse cluster setups using Distributed tables, because the analyzer behaves differently in that context. 3
• Query-level fixes: For the traces.metrics case, the preferred long-term fix is restructuring the query (PR #14432 wraps the problematic subquery) rather than relying solely on optimizer settings. 3

Key Files#