What causes "TIMED_OUT" in actualbudget/actual?

Retry the sync later — timeouts are usually transient

TIMED_OUT

TIMED_OUT

Error message

TIMED_OUT

What it means

Returned by getFailedSyncError when bank_sync_status is 'timed-out'. The last synchronization request exceeded the allowed time window — the bank or aggregator did not respond in time, so the sync failed on a deadline rather than a credential problem.

Source

Thrown at packages/desktop-client/src/accounts/syncStatus.ts:32

export function getFailedSyncError(
  account: Pick<AccountEntity, 'bank_sync_status' | 'account_sync_source'>,
): { type: string; code: string } {
  switch (account.bank_sync_status) {
    case 'reauth-required':
      if (account.account_sync_source === 'simpleFin') {
        return { type: 'INVALID_ACCESS_TOKEN', code: 'INVALID_ACCESS_TOKEN' };
      }
      return { type: 'ITEM_ERROR', code: 'ITEM_LOGIN_REQUIRED' };
    case 'attention-required':
      return {
        type: 'ACCOUNT_NEEDS_ATTENTION',
        code: 'ACCOUNT_NEEDS_ATTENTION',
      };
    case 'rate-limit-exceeded':
      return { type: 'RATE_LIMIT_EXCEEDED', code: 'RATE_LIMIT_EXCEEDED' };
    case 'timed-out':
      return { type: 'TIMED_OUT', code: 'TIMED_OUT' };
    case 'account-missing':
      return { type: 'ACCOUNT_MISSING', code: 'ACCOUNT_MISSING' };
    default:
      return { type: 'SYNC_ERROR', code: 'SYNC_ERROR' };
  }
}

View on GitHub (pinned to d4334cb6e6)

Solutions

Retry the sync later — timeouts are usually transient
Retry outside the bank's maintenance window if known
Reduce initial transaction history span to shorten the sync request
Check the provider status page / server network connectivity if it recurs

Example fix

// before
await syncAccount(account.id); // times out again immediately
// after
if (getFailedSyncError(account).code === 'TIMED_OUT') {
  await sleep(backoffMinutes(5));
  await syncAccount(account.id); // retry after backoff
}

Defensive patterns

Strategy: retry

Validate before calling

const err = getFailedSyncError(account);
if (err.code === 'TIMED_OUT') {
  // schedule a delayed retry
}

Type guard

function isTimedOut(v) {
  return !!v && typeof v === 'object' && v.code === 'TIMED_OUT';
}

Prevention

Use exponential backoff for timed-out syncs
Avoid syncing during known bank maintenance windows
Limit initial history fetch size to shorten sync requests

When it happens

Trigger: Calling getFailedSyncError on an account with bank_sync_status === 'timed-out' after a sync request aborted on a deadline.

Common situations: Slow or degraded bank APIs; aggregator timeouts during maintenance windows; very large transaction history fetches; network interruptions between server and provider.

Related errors

AI-assisted analysis of actualbudget/actual@d4334cb6e6 (2026-08-29). Data as JSON: /api/errors/aa7c36a24153728c. Report an issue: GitHub.