Skip to content

A local-first personal finance app

[AI] API: improve messaging for version/schema mismatch errors (#8026)

Matiss Janis Aboltins56512ab1ddaa
diff --git a/packages/loot-core/src/server/api.ts b/packages/loot-core/src/server/api.ts
index 936f9c7e3f..5f51b30896 100644
--- a/packages/loot-core/src/server/api.ts
+++ b/packages/loot-core/src/server/api.ts
@@ -225,7 +225,9 @@ handlers['api/download-budget'] = async function ({ syncId, password }) {
await handlers['load-budget']({ id: localBudget.id });
const result = await handlers['sync-budget']();
if (result.error) {
- throw new Error(getSyncError(result.error.reason, localBudget.id));
+ throw new Error(
+ getSyncError(result.error.reason, localBudget.id, result.error.meta),
+ );
}
return;
}
@@ -254,7 +256,7 @@ handlers['api/sync'] = async function () {
const { id } = prefs.getPrefs();
const result = await handlers['sync-budget']();
if (result.error) {
- throw new Error(getSyncError(result.error.reason, id));
+ throw new Error(getSyncError(result.error.reason, id, result.error.meta));
}
};
diff --git a/packages/loot-core/src/shared/errors.test.ts b/packages/loot-core/src/shared/errors.test.ts
new file mode 100644
index 0000000000..e4d67423ae
--- /dev/null
+++ b/packages/loot-core/src/shared/errors.test.ts
@@ -0,0 +1,63 @@
+import { getDownloadError, getSyncError } from './errors';
+
+const SCHEMA_MISMATCH_MESSAGE =
+ 'This budget could not be loaded because it uses a newer database schema than this version of Actual supports. Make sure you are using the latest version, then try again.';
+
+const schemaMismatchMeta = {
+ error: { message: 'no such column: cleanup_def', stack: '' },
+ query: { sql: 'UPDATE categories SET cleanup_def = ? WHERE id = ?' },
+};
+
+const unrelatedMeta = {
+ error: { message: 'UNIQUE constraint failed', stack: '' },
+ query: { sql: 'INSERT INTO categories (id) VALUES (?)' },
+};
+
+describe('getDownloadError', () => {
+ it('returns a version-mismatch message for missing-column schema errors', () => {
+ expect(
+ getDownloadError({ reason: 'invalid-schema', meta: schemaMismatchMeta }),
+ ).toBe(SCHEMA_MISMATCH_MESSAGE);
+ });
+
+ it('returns a version-mismatch message for missing-table schema errors', () => {
+ expect(
+ getDownloadError({
+ reason: 'invalid-schema',
+ meta: { error: { message: 'no such table: foo', stack: '' } },
+ }),
+ ).toBe(SCHEMA_MISMATCH_MESSAGE);
+ });
+
+ it('does not report a schema mismatch for other invalid-schema failures', () => {
+ expect(
+ getDownloadError({ reason: 'invalid-schema', meta: unrelatedMeta }),
+ ).not.toBe(SCHEMA_MISMATCH_MESSAGE);
+ });
+
+ it('does not report a schema mismatch when meta is missing', () => {
+ expect(getDownloadError({ reason: 'invalid-schema' })).not.toBe(
+ SCHEMA_MISMATCH_MESSAGE,
+ );
+ });
+});
+
+describe('getSyncError', () => {
+ it('returns a version-mismatch message for missing-column schema errors', () => {
+ expect(
+ getSyncError('invalid-schema', 'budget-id', schemaMismatchMeta),
+ ).toBe(SCHEMA_MISMATCH_MESSAGE);
+ });
+
+ it('does not report a schema mismatch for other invalid-schema failures', () => {
+ expect(getSyncError('invalid-schema', 'budget-id', unrelatedMeta)).not.toBe(
+ SCHEMA_MISMATCH_MESSAGE,
+ );
+ });
+
+ it('does not report a schema mismatch when meta is missing', () => {
+ expect(getSyncError('invalid-schema', 'budget-id')).not.toBe(
+ SCHEMA_MISMATCH_MESSAGE,
+ );
+ });
+});
diff --git a/packages/loot-core/src/shared/errors.ts b/packages/loot-core/src/shared/errors.ts
index 47dd43d865..332d0d7965 100644
--- a/packages/loot-core/src/shared/errors.ts
+++ b/packages/loot-core/src/shared/errors.ts
@@ -5,6 +5,25 @@ type ErrorWithMeta = {
meta?: unknown;
};
+function isDatabaseSchemaMismatch(meta?: unknown): boolean {
+ if (
+ meta &&
+ typeof meta === 'object' &&
+ 'error' in meta &&
+ meta.error &&
+ typeof meta.error === 'object' &&
+ 'message' in meta.error &&
+ typeof meta.error.message === 'string'
+ ) {
+ return /no such (column|table)/i.test(meta.error.message);
+ }
+ return false;
+}
+
+function getSchemaMismatchError() {
+ return 'This budget could not be loaded because it uses a newer database schema than this version of Actual supports. Make sure you are using the latest version, then try again.';
+}
+
export function getUploadError({ reason, meta }: ErrorWithMeta) {
switch (reason) {
case 'unauthorized':
@@ -48,6 +67,10 @@ export function getDownloadError({
meta?: unknown;
fileName?: string;
}) {
+ if (reason === 'invalid-schema' && isDatabaseSchemaMismatch(meta)) {
+ return getSchemaMismatchError();
+ }
+
switch (reason) {
case 'network':
case 'download-failure':
@@ -111,9 +134,11 @@ export function getTestKeyError({ reason }: ErrorWithMeta) {
}
}
-export function getSyncError(error: string, id: string) {
+export function getSyncError(error: string, id: string, meta?: unknown) {
if (error === 'out-of-sync-migrations' || error === 'out-of-sync-data') {
return t('This budget cannot be loaded with this version of the app.');
+ } else if (error === 'invalid-schema' && isDatabaseSchemaMismatch(meta)) {
+ return getSchemaMismatchError();
} else if (error === 'budget-not-found') {
return t(
'Budget "{{id}}" not found. Check the ID of your budget in the Advanced section of the settings page.',
diff --git a/upcoming-release-notes/8026.md b/upcoming-release-notes/8026.md
new file mode 100644
index 0000000000..81fbdc1b20
--- /dev/null
+++ b/upcoming-release-notes/8026.md
@@ -0,0 +1,6 @@
+---
+category: Enhancements
+authors: [MatissJanis]
+---
+
+Show a clear "update required" message instead of a cryptic `no such column` error when an outdated client or API connects to a budget that uses a newer database schema