RuntimeError: ClickHouse query failed with HTTP status 500

快速结论：这个报错通常出现在 LiteLLM 使用 ClickHouse 存储 trace 时，读取 span 数量超过 1000 条的 trace detail 会返回 HTTP 500。优先确认是否触发了 ClickHouse reader 的 max_result_rows=1000 行数上限。

适用环境：LiteLLM v1.105.0-dev.2（已安装包与 UI 报告 1.105.0）；官方镜像 ghcr.io/berriai/litellm:v1.105.0-dev.2@sha256:c4bce2a2611e78a311d944be7a53953d0d7df3d9d08697e5dbae409d0d9210c7；Linux arm64 manifest sha256:05d937b2003b7b883d09fbbc49a4f0f48863178344ab73d42120202846c07d8f；ClickHouse 26.9.6.6；使用 ClickHouse 作为 tracing store，reader 为 SELECT-only 的 Rust ClickHouse reader。

最快修复方案：暂无确认的一步修复方案。Issue 中确认的修复版本为 v1.106.0-dev.1（tag commit bce020f8d8b0628f65fb6eaf81a6b219a2203f7e），重测时 1001 span 的 HTTP 500 / ClickHouse Code 396 未再复现。可优先尝试升级到该已验证版本。

注意事项：v1.106.0-dev.1 的验证覆盖了 999、1000、1001、5001 span 的存储与 API 读取，以及 200-span 分页；501 条完整展开且 Live enabled 的 5001-span 场景在加载 4200 步后超时，但这属于 UI 大 trace 性能问题，不代表 HTTP 500 缺陷仍存在。Investigation-worker 执行路径未测试。

问题场景

用户在 LiteLLM 中配置 ClickHouse 作为 tracing store 后，写入一条包含 1001 个小型 span 的 trace，存储本身成功，但通过 GET /v1/traces/{trace_id} 读取 trace detail 时返回 HTTP 500。Lens UI 中该 trace 会出现在列表里，但打开时报 “Could not load trace” / “Internal server error”。该问题不依赖 UI，直接调用 API 也能复现。相同结构与设置下，999 或 1000 个 span 的 trace 可以正常加载。

报错原文

RuntimeError: ClickHouse query failed with HTTP status 500

ClickHouse returns Code 396 (`TOO_MANY_ROWS_OR_BYTES`)

原因分析

Rust ClickHouse reader 对查询强制设置了 max_result_rows=1000，并且 overflow mode 为 throw。当 trace 内的 span 数量超过 1000 时，ClickHouse 返回 Code 396 TOO_MANY_ROWS_OR_BYTES，最终表现为 trace detail 接口 HTTP 500。该问题与数据是否完整写入无关：Issue 中确认 1001 行数据均已存在，但读取路径失败。

环境排查

确认 LiteLLM 版本是否包含该 reader 行数限制。Issue 中 v1.105.0-dev.2 可复现，v1.106.0-dev.1 已修复。
确认 tracing store 是否为 ClickHouse：general_settings.tracing.store: clickhouse。
确认 CLICKHOUSE_URL 与 CLICKHOUSE_READER_URL 指向的 ClickHouse 实例和数据库版本；Issue 中使用 ClickHouse 26.9.6.6，CLICKHOUSE_DATABASE=litellm。
确认 reader 是否为 SELECT-only 配置，且允许 Rust reader 所需的 per-query settings。
确认触发问题的 trace span 数量是否大于 1000。
确认 PostgreSQL 仅作为 DATABASE_URL 的元数据存储，不承载 ClickHouse trace 读取逻辑。

解决步骤

先复现并确认 span 数量边界：用 Issue 中的脚本分别提交 999、1000、1001 个 span，观察 GET /v1/traces/{trace_id} 的返回状态码。999 和 1000 应为成功，1001 触发 HTTP 500。
检查 LiteLLM 版本。如果运行的是 v1.105.0-dev.2 或同样包含 max_result_rows=1000 且 overflow mode 为 throw 的构建，该限制会导致 Code 396。
升级到 Issue 中已验证修复的 v1.106.0-dev.1（tag commit bce020f8d8b0628f65fb6eaf81a6b219a2203f7e）。Issue 评论摘要明确说明该版本上 1001 span 的 HTTP 500 / ClickHouse Code 396 不再复现。
升级后使用相同脚本重测 999、1000、1001 以及 5001 span 的写入与读取，确认 API 不再返回 HTTP 500。
如需验证分页读取，使用 200-span 分页检查 span ID、父子关系与顺序是否完整保留。

验证方法

在修复版本上重跑 Issue 中的 rows_repro.py，确认 1001 span 的 trace 通过 GET /v1/traces/{trace_id} 返回成功而非 HTTP 500；同时确认存储的数据行数与 span ID、parent relationships、ordering 保持一致。Lens 中应能正常加载该 trace 及分页内容，不再出现 “Could not load trace” / “Internal server error”。