Most bank-sync problems are misclassified, not mysterious. A missing transaction might be absent at the bank connector, present in the SimpleFIN response but outside the requested range, mapped to another local account, or rejected by deduplication.
Record four timestamps
Capture last provider refresh, last successful SimpleFIN fetch, newest transaction returned and newest transaction written locally. Also record the requested start and end dates. A single “synced” timestamp hides the first useful clue.
Do not expect unlimited history. The Bridge guide caps requested windows at 90 days and available history varies by institution. For older backfill, a bank export may be more reliable. For ongoing sync, overlap recent days so late-posting and pending-to-posted changes are caught.
Credential failures
A setup token is single-use. If claim succeeded but the app failed before storing the access URL, retrying the same setup token will not recreate it—generate a fresh one. If the app offers a supported reset path, use it rather than editing its database.
The access URL includes credentials. Partial copying, incorrect decoding or unsafe string concatenation can cause authorization errors. Keep it intact and build the /accounts request with a URL library.
Quotas and schedules
The Bridge guide expects no more than about 24 requests per day and recommends spreading work away from the top of the hour. Add jitter. On throttling or transient network errors, back off; regenerating credentials will not fix a quota problem.
Diagnostic sequence
Check the provider connection
Can it see the institution and a recent refresh, or does it request reauthorisation?
Check credential metadata
Confirm the secret exists without printing it.
Run one bounded fetch
Request a recent window for one account and save a redacted fixture.
Read structured errors
Inspect v2 `errlist` before scanning transactions.
Verify account mapping
Match remote IDs to the intended local accounts.
Trace one missing record
Follow its provider ID through normalize and upsert.
Reconcile counts and balances
HTTP 200 alone is not proof of correctness.
Missing, stale and duplicate records
If a transaction appears remotely but not locally, inspect date boundaries, time zones, currency conversion, account filters and duplicate keys. If two legitimate recurring charges collapse, replace fuzzy matching with stable provider IDs. If pending and posted versions duplicate, upsert inside an overlap window.
Stale balances with fresh transactions can indicate that balance handling and transaction handling follow different code paths. Compare provider freshness, returned balance fields and the application’s reconciliation logic.
App-specific reset paths
Actual Budget documents a credential reset from the Add Account menu. Sparky Budget may require removing its stored access_url.txt, generating a new setup token, updating configuration and restarting Docker. Firefly III uses the separate Data Importer, so review its configuration and logs rather than only the main app.
Repair safely
| Problem | Safe action | Avoid |
|---|---|---|
| Claim lost before save | Generate a new setup token | Retry consumed token forever |
| One institution needs attention | Reauthorise that connection | Delete all accounts |
| Older history absent | Use file backfill | Unbounded repeated requests |
| Pending/posted duplicate | Upsert stable ID with overlap | Fuzzy merchant matching |
| Stale data with error | Show stale state and error | Green sync badge |
| Quota response | Back off with jitter | Credential rotation |
Choose the narrowest corrective action.
When to escalate
Escalate with a redacted diagnostic bundle: provider name, protocol version, remote account ID suffix, request window, timestamps, HTTP status, structured error code and record counts. Never include the full access URL, setup token or raw unrelated transactions.