actualbudget/actual

Improve error messaging when API and server versions mismatch

Open

#6633 opened on Jan 12, 2026

View on GitHub
 (0 comments) (0 reactions) (0 assignees)JavaScript (7,129 stars) (603 forks)batch import
APIhelp wantedtech debt

Description

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

Contributor guide

Tech stack
javascriptnodejsrest api
Domain
backendapi
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
half day
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Node.jsREST API concepts
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80
Research direction
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.