actualbudget/actual · error

ACCOUNT_NEEDS_ATTENTION

ACCOUNT_NEEDS_ATTENTION

Error message

ACCOUNT_NEEDS_ATTENTION

What it means

Returned by getFailedSyncError when an account's bank_sync_status is 'attention-required'. The provider reports the linked account needs user intervention (consent issues, new terms, account-level problem detected by the aggregator) before sync can continue.

Source

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

    status !== 'ok' &&
    status !== 'pending' &&
    status !== 'sync-requested'
  );
}

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

1. Open the account's sync error UI and follow the 'account needs attention' guidance for the provider
2. Log into online banking directly and resolve any prompts (terms, verification, closure notices)
3. If the account was closed/converted, update or re-link it to the new account
4. Check the provider status page for a known institution outage

Example fix

// before
const err = getFailedSyncError(account); // ACCOUNT_NEEDS_ATTENTION
// after
// resolve prompts in the bank portal, then:
await syncAccount(account.id); // status clears

function needsAttention(account) {
  return account.bank_sync_status === 'attention-required';
}

function isSyncErrorDescriptor(v) {
  return !!v && typeof v === 'object' && typeof v.type === 'string' && typeof v.code === 'string';
}

When it happens

Trigger: Calling getFailedSyncError on an account with bank_sync_status === 'attention-required', regardless of sync source.

Common situations: Bank requires accepting new terms in online banking; aggregator flags the account for review; account closed or converted; institution outage leaves the status stuck.

Related errors

• response.reason || response.error_code
• response.reason || response.error || fallbackMessage
• Account with ID ${upgradingId} not found.
• Bank with ID ${bankId} not found.
• `payeeName` is required when adding a transaction

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