New to OtterLedger? Read the Documentation
45 Guides Available Quick Start Guide
Learn AI Categorization View Guide
Have Questions? Check the FAQ
New to OtterLedger? Read the Documentation
45 Guides Available Quick Start Guide
Learn AI Categorization View Guide
Have Questions? Check the FAQ
All Docs

Troubleshooting

Guide 41: Troubleshooting

Solutions to common issues

Application Issues

OtterLedger won't start

  1. Restart your computer
  2. Check if another instance is running
  3. Verify .NET 8 runtime is installed
  4. Try running as administrator
  5. Reinstall OtterLedger

Application is slow

  1. Close other applications
  2. Check file size (large files take longer)
  3. Rebuild database indexes (Settings → Advanced → Rebuild)
  4. Check for pending updates

Crashes on startup

  1. Delete settings database (will reset preferences)
    • Windows: %AppData%\OtterLedger\settings.db
    • Mac: ~/Library/Application Support/OpenLedger/settings.db
  2. Restore from backup if file is corrupted

Data Issues

Transactions not saving

  1. Check if file is read-only
  2. Verify disk space available
  3. Close and reopen file
  4. Check file permissions

Balance doesn't match bank

  1. Run reconciliation
  2. Check for pending transactions
  3. Look for duplicates
  4. Verify cleared status

Missing transactions after import

  1. Check import date range
  2. Look in correct account
  3. Review duplicate detection settings
  4. Check import log for errors

Bank Connection Issues

SimpleFin not syncing

  1. Check internet connection
  2. Verify SimpleFin credentials
  3. Refresh bank connection
  4. Some banks have delays (wait 24 hours)

Bank login fails

  1. Update bank credentials
  2. Check for bank website changes
  3. Clear connection and re-add
  4. Contact bank for API access

Duplicate transactions from sync

  1. Adjust duplicate detection settings
  2. Review and merge duplicates
  3. Adjust sync date range

Import Issues

QFX/OFX file not importing

  1. Verify file isn't corrupted
  2. Check file encoding
  3. Open in text editor to verify format
  4. Try exporting from bank again

CSV import problems

  1. Verify column mapping
  2. Check date format matches
  3. Remove special characters from amounts
  4. Ensure UTF-8 encoding

Wrong amounts after import

  1. Check decimal separator settings
  2. Verify amount column mapping
  3. Look for currency conversion issues

PDF Import Issues

PDF file not parsing correctly

  1. Verify the PDF is a text-based statement (not a scanned image)
  2. Try the "Flip Signs" button if amounts seem inverted
  3. Check if NegateStatementAmounts is toggled correctly for credit card statements
  4. Some bank PDF formats are not yet supported — try importing as CSV instead

PDF balance doesn't match

  1. Verify the correct statement period was extracted
  2. Check if multi-section statements have all sections included
  3. Use the "Flip Signs" button for liability accounts

Reconciliation Issues

Can't find matching transaction

  1. Widen date range
  2. Search by amount only
  3. Check for splits
  4. Verify transaction wasn't deleted

Statement doesn't balance

  1. Verify beginning balance
  2. Check for missing transactions
  3. Review cleared transactions
  4. Look for duplicate entries

AI Issues

AI not categorizing

  1. Check AI settings enabled
  2. Verify API key (for cloud)
  3. Check local LLM is running
  4. Review error logs

Wrong categories from AI

  1. Create rules for common payees
  2. Adjust confidence threshold
  3. Review and correct to train the system
  4. Check category mappings

XGBoost model not working

  1. Verify you have enough categorized transactions (minimum ~50) to train the model
  2. Go to Settings → AI → XGBoost and click "Train Model"
  3. Check that the model status shows "Trained"
  4. If accuracy is low, categorize more transactions and retrain

Web search enrichment errors

  1. Google Search may be rate-limited (HTTP 429) — DuckDuckGo will be used as fallback
  2. Check Settings → AI → Web Search to verify enrichment is enabled
  3. Some cryptic payees may not return useful results from web search

Performance Issues

Reports are slow

  1. Narrow date range
  2. Filter to specific accounts
  3. Check for large transaction count
  4. Export and view externally

Search is slow

  1. Rebuild search index
  2. Use more specific terms
  3. Filter by date range first

Getting Help

Log Files

Location: %AppData%\OtterLedger\logs\

  • Include logs when reporting issues
  • Logs contain no personal financial data

Support Resources

  1. Check this troubleshooting guide
  2. Search community forums
  3. Review release notes for known issues
  4. Report bugs on GitHub

See also: Guide 42: FAQ