Dashboard widget API hard-codes minVersion=2 → API-created widgets always 500 without v4 write mode

问题场景

自托管 Langfuse 实例（非 v4 write mode）上，用户通过 Dashboard Widget API（POST /api/public/unstable/dashboard-widgets）创建小组件并加入仪表板后，仪表板加载时小组件始终显示 Internal Server Error，路径为 dashboard.executeQuery。即使后续编辑小组件（修改指标、筛选等）也无法恢复。但通过 UI 创建的同配置小组件可以正常渲染。

报错原文

Internal Server Error
Internal error. Please check error logs in your self-hosted deployment.
Path: dashboard.executeQuery

当 API 创建小组件时使用 v2-only 的指标（如 measure: "traces" + view: "observations"）时还会出现：

Measure "traces" is not available for view "observations" in version "v2"

原因分析

根因是 normalizePublicDashboardWidgetInput 函数中硬编码 minVersion = 2（位于 web/src/features/widgets/server/public-dashboard-widget-service.ts），且 API 请求体没有字段可以覆盖此值。该 minVersion 被传递到 DashboardWidget.tsx 后，强制所有 API 创建的小组件使用 v2 查询引擎（metricsVersion = "v2"）。v2 引擎依赖 events_* 表，而这些表仅在 v4 write mode 下存在。未启用 v4 write mode 的部署中，v2 指标接口会返回明确错误，但小组件渲染路径缺少相应守卫，直接返回 500。UI 创建的小组件正常是因为 UI 会根据部署模式选择正确的查询引擎版本。

环境排查

• 确认自托管部署的 Langfuse 版本（可通过 /api/public/health 或 Helm chart 版本查看）。
• 检查部署是否启用了 v4 write mode（通常在环境变量 LANGFUSE_V4_WRITE_MODE=true 或通过 Helm values 配置）。
• 查看小组件的 minVersion 字段（可通过 API 获取小组件详情，例如 GET /api/public/unstable/dashboard-widgets/{widgetId}，如果返回 minVersion: 2 则确认受影响）。

解决步骤

1. 升级 Langfuse 到 v3.224.4 或更高版本。该版本已修复 API 创建小组件时硬编码 minVersion 的问题。升级后新创建的小组件将根据部署模式自动选择版本。
2. 清理已有损坏的小组件。升级后，之前通过 API 创建且 minVersion=2 的小组件仍然无法渲染。需要手动删除这些小组件（或通过 API 更新 minVersion 为 1，但官方未提供明确更新方式，建议直接删除重建）。
3. 可选：考虑迁移到 v4 write mode。如果部署支持并愿意升级，按照 v3 → v4 升级指南启用 v4 write mode，可从根本上避免版本兼容问题。

验证方法

升级后，使用相同 API 请求创建小组件并加入仪表板，确认小组件能够正常渲染（无 500 错误）。同时可以调用 GET /api/public/unstable/dashboard-widgets/{widgetId} 查看新创建小组件的 minVersion 字段，应为 1（或与部署模式对应的值）。

参考来源

langfuse/langfuse #15549 Dashboard widget API hard-codes minVersion=2 → API-created widgets always 500 without v4 write mode

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。