actualbudget/actual

Improve error messaging when API and server versions mismatch

Open

#6,633 创建于 2026年1月12日

在 GitHub 查看
 (0 评论) (0 反应) (0 负责人)JavaScript (7,129 star) (603 fork)batch import
APIhelp wantedtech debt

描述

Problem

When the API client version and server version mismatch, the application shows cryptic error messages that don't clearly indicate the root cause. For example, when using an older API version (v25.12.0) with a newer server version (v26.1.0), users see errors like:

Error: no such column: custom_reports.trim_intervals

This makes it difficult for users to diagnose that the issue is caused by a version mismatch between the API client and server.

Expected Behavior

When there's a version mismatch between the API client and server, the application should:

  • Detect the version mismatch
  • Throw a clear, friendly error message explaining the problem
  • Guide users on how to resolve it (e.g., "API version X.X.X does not match server version Y.Y.Y. Please ensure both are using the same version.")

Additional Context

This issue was identified when a user was using the lunchflow tool with API version v25.12.0 while running Actual server v26.1.0.

Backlink: https://github.com/actualbudget/actual/issues/6619 Requested by: @MatissJanis

贡献者指南

技术栈
javascriptnodejsrest api
领域
backendapi
议题类型
feature
难度面向新贡献者的预计实现难度，1 表示很小改动，5 表示专家级工作。
3
预计时间有经验贡献者完成调查、实现、测试并准备 pull request 的粗略时间范围。
half day
活动状态议题当前的可参与程度：新鲜、活跃、陈旧、阻塞或等待维护者输入。
fresh
清晰度议题是否清楚说明期望改动、验收标准和下一步。
clear
前置要求
Node.jsREST API concepts
新手友好度1-100 的估计分数，表示该议题对首次贡献者的友好程度。
80
研究方向
Start by examining the client server communication in the repository, possibly in the API client library or the server's request handling. Look for version checking mechanisms in the HTTP headers or configuration files. Then implement a version comparison function that throws a descriptive error message when a mismatch is detected, and update the client library's error handling to catch and display it. Check the linked issue #6619 for reproduction steps and user feedback on the error.
Improve error messaging when API and server versions mismatch · actualbudget/actual#6633 | Good First Issue