>
Download

Documentation

Learn everything you'll ever need to get the most out of BillKit

>
Troubleshooting Guide

This guide provides solutions to common problems you might encounter while using BillKit. Issues are organised by category for easy reference.

Installation Issues

BillKit won't open after installation

Double-clicking BillKit shows nothing, or app bounces once and closes.

Possible causes

  • macOS security blocking unverified app
  • Corrupted download
  • Insufficient macOS version

Solutions

Check macOS version:

  1. Click Apple menu → About This Mac
  2. Verify macOS 14.6+ (Sonoma) or later
  3. Update macOS if needed

Reinstall from App Store:

  1. Open App Store application
  2. Go to your account (click your profile icon)
  3. Find BillKit in your purchased apps
  4. Click the download/cloud icon to reinstall
  5. Wait for installation to complete

Clear App Store cache:

  1. Quit App Store completely
  2. Hold Option key and click Apple menu
  3. Select "Library" from Go menu in Finder
  4. Navigate to Caches → com.apple.appstore
  5. Delete contents of this folder
  6. Restart Mac
  7. Reinstall BillKit from App Store

Launch Issues

"BillKit is damaged and can't be opened" error

macOS Gatekeeper blocks the app.

Solution

  1. Open Terminal
  2. Run: xattr -cr /Applications/BillKit.app
  3. This removes quarantine attribute
  4. Try launching again

Business & Setup Issues

Can't create first business

The "Add Business" button is disabled or shows error.

Possible cause

  • Database not initialized
  • Permissions issue

Solution

  1. Quit and restart BillKit
  2. Check Console.app for error messages
  3. Try resetting app data (Settings → Reset App Data) as last resort

Business selector is empty

Sidebar shows no businesses, can't access most features.

Solution

You need to create at least one business first. See creating a business in the managing businesses documentation.

AI Processing Issues

"API key not set" error when processing

Files fail to process with API key error.

Solution

Ensure you have selected an AI Provider and have set an API Key for that provider. See AI Services in the settings and preferences documentation

Invoice processing fails with "Invalid API key"

Processing starts but fails immediately with authentication error.

Possible cause

  • API key copied incorrectly (extra spaces, missing characters)
  • API key expired or revoked
  • Wrong provider selected (Claude key with OpenAI selected)

Solution

  1. Visit your AI provider's console (console.anthropic.com or platform.openai.com)
  2. Verify API key is active and not revoked
  3. Create new API key if needed
  4. Copy entire key carefully (including sk-ant- or sk- prefix)
  5. Review the AI Services documentation for instructions on managing API Keys.

AI extracts wrong amounts or dates

Extracted total is £100 but invoice shows £125, or dates are incorrect.

Possible cause

  • Invoice format is non-standard
  • Scanned invoice is blurry or low quality
  • Multiple totals on invoice (AI picked wrong one)

Solution

Edit the expense manually as detailed in the managing expenses documentation.

Processing is very slow (30+ seconds per invoice)

Each invoice takes much longer than expected 5-15 seconds.

Possible cause

  • Large file sizes (10+ MB)
  • Many pages (50+ pages in PDF)
  • Slow internet connection
  • AI service experiencing high traffic

Solution

  1. Check file sizes and compress large PDFs before uploading if needed
  2. Split multi-page PDFs if possible
  3. Test internet speed to ensure you have a stable connection
  4. Try a different AI provider (switch from Claude to OpenAI or vice versa)
  5. Process invoices during off-peak hours
  6. Process fewer files at once (5-10 instead of 50)

Expense Management

Can't create new expense - upgrade prompt appears

Clicking + button shows "Upgrade Required" dialog.

Possible cause

You've reached Basic tier limit (25 expenses per 28 days).

Solution

  1. Wait: Oldest expenses age beyond 28-day window (count decreases automatically)
  2. Upgrade to Pro: Unlimited expenses
  3. Delete test/duplicate expenses: Frees up count (but doesn't reduce usage immediately)

Expense not appearing in All Expenses

Created expense but can't find it in list.

Possible cause

  • Wrong business selected
  • Wrong currency selected
  • The expense is outside the set date range
  • Filters maybe hiding the expense
  • The expense is outside current page (pagination)

Solution

  1. Check correct business selected in sidebar
  2. Click filter icon and then click Clear Filters
  3. Clear search field (click X)
  4. Scroll to bottom and click Load More to see additional pages
  5. Sort by Created Date descending to find recent expenses at the top

Currency totals don't match expectations

Footer shows "GBP: £1,000" but you expected "GBP: £1,500".

Possible cause

  • Filters active (showing subset of expenses)
  • Some expenses in different currency
  • Viewing different business

Solution

  1. Clear all filters to see full dataset
  2. Check footer shows all currencies (may have USD, EUR in addition to GBP)
  3. Verify the correct business is active
  4. Export to CSV and sum manually to verify

File Upload & Processing

Drag and drop not working

Dragging files to drop zone doesn't upload them.

Solution

  1. Ensure you're dragging onto the drop zone area (top section of Upload Files screen)
  2. Try click-to-browse instead: Click drop zone → Choose files
  3. Check file types are supported (PDF, PNG, JPEG, HEIC only)
  4. Check file sizes are under 32 MB

"File too large" error

Uploads are rejected with file size error.

Possible cause

One or more files exceeds the 32 MB limit for AI processing.

Solution

  1. Compress PDF using Preview → Export → Reduce File Size
  2. Reduce image resolution before uploading
  3. Split large multi-page PDFs into smaller files
  4. Convert high-res photos to JPEG with lower quality setting

"PDF has too many pages" error

The uploaded PDF was rejected with a page count error.

Possible cause

PDF exceeds 100 pages.

Solution

  1. Split PDF into multiple files (Pages 1-100, Pages 101-200, etc.)
  2. Extract only invoice pages (remove attachments, supporting docs)

HEIC files show error

iPhone photos won't upload or fail to convert.

Solution

  1. Convert HEIC to JPEG before uploading:
    • Open photo in Preview (Mac)
    • File → Export → Format: JPEG
    • Save and upload the JPEG
  2. Change iPhone camera settings to save as JPEG instead of HEIC:
    • Settings → Camera → Formats → Most Compatible

Dashboard & Reporting

Dashboard shows "No data" despite having expenses

All charts are empty showing no data

Possible cause

  • Date range filter excludes all expenses
  • Wrong business selected
  • Wrong currency selected
  • No expenses actually exist in current business or currency

Solution

  1. Widen date range to "Last 12 Months" or "All Time"
  2. Verify correct business selected (check sidebar)
  3. Navigate away from Dashboard and back (triggers refresh)

Chart data doesn't update after adding expenses

I'm creating expenses but the Dashboard still shows old numbers.

Solution

  1. Change date range and change back (forces refresh)
  2. Navigate to different screen and back to Dashboard
  3. Restart BillKit if the issue persists

Export Issues

Export button is disabled

Can't click Export button for expenses or other data.

Possible cause

  • No business selected (for business-scoped exports)
  • No data exists to export
  • JSON format selected on Basic tier

Solution

  1. Select a business from dropdown (if available)
  2. Check data exists (e.g. expenses present in All Expenses screen)
  3. Switch to CSV format if on Basic tier

CSV opens with garbled text in Excel

Excel shows strange characters or formatting in the file

Possible cause

Encoding mismatch.

Solution

  1. Open Excel
  2. Data → From Text/CSV
  3. Select BillKit CSV file
  4. Choose "UTF-8" encoding
  5. Set delimiter to "Comma"
  6. Import and review data

ZIP export with invoice files fails

Export crashes or produces corrupted ZIP.

Possible cause

  • Insufficient disk space
  • Too many/too large invoice files
  • Memory limits

Solution

  1. Check available disk space (need 2x total file size free)
  2. Export smaller date ranges (one quarter at a time)
  3. Try exporting without invoice files to isolate issue

Backup & Restore

Backup creation fails or shows error

Clicking "Create Backup" fails with error message.

Possible cause

  • Insufficient disk space
  • Corrupted database
  • Missing invoice files
  • Permissions issue

Solution

  1. Check available disk space (need 2x database + invoice file size free)
  2. Try backing up to different location (Downloads folder first)
  3. Check Console.app for detailed error messages
  4. Restart BillKit and try again
  5. If database corrupted, fix corruption first (see "Database corruption error" section)

Restore fails with "Invalid backup file"

Selected backup ZIP shows error immediately.

Possible cause

  • ZIP file corrupted during download or transfer
  • Not a BillKit backup (wrong file selected)
  • ZIP not properly closed during creation

Solution

  1. Verify file is BillKit backup (filename starts with "BillKit-Backup-")
  2. Try different backup file
  3. Check ZIP file size matches expected size
  4. Re-create backup from source machine
  5. If downloaded from cloud, try downloading again

Restore fails with "Incompatible backup version"

Restore shows version mismatch error. e.g "Incompatible backup version: 2.0 (expected: 1.0)"

Possible cause

Backup created with different BillKit version.

Solution

  1. Update BillKit to latest version
  2. Create fresh backup from latest version
  3. Cannot restore newer version backups to older BillKit version
  4. Contact support if you need to migrate old backup to new version

Restore hangs or takes very long

Progress bar stuck at same step for 5+ minutes.

Possible cause

  • Very large backup (GB+ size)
  • Many invoice files (1000s of files)
  • Slow disk (external drive, network drive)

Solution

  1. Wait longer - large restores can take 5-10 minutes
  2. Check Activity Monitor - BillKit should show active CPU/disk usage
  3. If truly stuck (no disk activity), force quit and try again
  4. Restore to local disk first (faster), then move to external if needed

Restore completes but data is missing

Restore succeeds but some expenses or files missing.

Possible cause

  • Backup was created when some data was already deleted
  • Backup partial or corrupted
  • Wrong backup file selected (older backup)

Solution

  1. Check backup filename - date indicates when it was created
  2. Try different backup file (more recent)
  3. Verify backup ZIP contents (unzip manually and check folders)
  4. Create fresh backup from machine with complete data
  5. If no good backup exists, may need to re-enter data manually

App doesn't restart after restore

Restore shows 100% complete but app doesn't restart.

Solution

  1. Wait 5-10 seconds - restart may be delayed
  2. Check if app actually restarted (quit old window, new window opened)
  3. If stuck at 100%, manually quit BillKit (Command + Q)
  4. Reopen BillKit - restored data should load
  5. All data from backup should be present

After restore, API key missing

Can't process invoices after restore.

Possible cause

This is expected behavior. API keys are NOT included in backups for security.

Solution

Review the AI Services documentation for instructions on managing API Keys.

Settings & Configuration

Settings don't persist after restart

Appearance, currency, or other settings reset on next launch.

Possible cause

  • UserDefaults storage issue
  • Disk permissions
  • Disk full

Solution

  1. Check available disk space
  2. Verify BillKit has file system permissions. Look at System Preferences → Security & Privacy → Files and Folders
  3. Restart Mac and try again
  4. Reinstall BillKit as last resort

Can't delete API key

Delete API Key button doesn't work or the API key reappears after deleting.

Possible cause

Keychain access issue.

Solution

  1. Open Keychain Access app (in /Applications/Utilities)
  2. Search for "BillKit"
  3. Delete BillKit keychain items manually
  4. Restart BillKit

Performance Issues

BillKit slow to launch

The app takes 30+ seconds to open after double-clicking.

Possible cause

  • Large database (10,000+ expenses)
  • Database integrity check taking long
  • Disk fragmentation

Solution

  1. Check database size: ~/Library/Containers/CodelDev.BillKit/Data/Library/Application Support/
  2. Archive old expenses (export and delete)
  3. Shorten log retention (Settings → General → Log Retention)
  4. Restart Mac to clear memory/cache

UI freezes or becomes unresponsive

BillKit stops responding to clicks and/or the mac beach ball appears.

Possible cause

  • Processing many files simultaneously
  • Loading very large table (1000s of expenses)
  • Memory leak (rare)

Solution

  1. Wait 30-60 seconds (may just be slow operation)
  2. Force quit and restart:
    • Press Command + Option + Escape
    • Select BillKit
    • Click Force Quit
  3. Reduce pagination (load fewer items per page)
  4. Process files sequentially instead of parallel

Subscription & Billing

Upgraded but still seeing limits

I paid for Pro but I'm still hitting Basic tier limits.

Solution

  1. Quit BillKit completely
  2. Reopen BillKit
  3. Check Subscription screen shows "Pro" status
  4. Check your apple subscriptions via the app store.

Charged after cancelling subscription

I have been billed despite cancellation.

Possible cause

  • Cancelled after billing cycle started
  • Cancellation didn't process
  • Looking at old charge (before cancellation)

Solution

Contact Apple support directly. We do not deal with payments or refunds.

Data & Storage Issues

"Database corrupted" error

The app shows corruption error on startup.

Automatic recovery: BillKit attempts automatic repair. Usually succeeds.

Solution

  1. Quit BillKit
  2. Restore from backup:
    • Time Machine: Browse to BillKit container, restore
    • Manual backup: Replace BillKit container folder with backup
  3. Restart BillKit
  4. If no backup, may need to Reset App Data and re-enter

Prevention:

  • Always quit BillKit cleanly (don't force-quit during saves)
  • Keep regular backups
  • Don't manually edit database files

BillKit using too much disk space

The app container folder is multiple GB.

Solution

  1. Check invoice file sizes in Documents/businesses folders
  2. Delete old invoice files if no longer needed (after exporting)
  3. Delete old expenses
  4. Shorten log retention (Settings → General)
  5. Export and archive old data, then delete from BillKit

Invoice files missing or can't download

An expense shows attached file but download fails.

Possible cause

  • File manually deleted from disk
  • File moved
  • Permissions issue

Solution

  1. Check ~/Library/Containers/CodelDev.BillKit/Data/Documents/businesses/[business-uuid]/invoices/
  2. Verify the file exists
  3. If missing, restore from backup
  4. If moved, move back to correct location
  5. If permanently lost, re-upload the file

When All Else Fails

Nuclear option: Reset and restore

If BillKit is completely broken

  1. Export everything first (if possible):

    • Export Data → Export all businesses, expenses, categories, vendors, audit logs
    • Save exports to safe location

  2. Reset BillKit:

    • Click Reset App Data in sidebar
    • Confirm deletion

  3. Restart BillKit:

    • App returns to first-launch state

  4. Restore from backup:

    • Time Machine or manual container folder backup
    • Or manually re-enter data from exports

Additional Help

If the documentation and our FAQ are unable to help you resolve an issue, please do reach out to us providing:

  • BillKit version. You can find this at the bottom of the sidebar.
  • macOS version. You can find this in "About This Mac"
  • Steps to reproduce. Tell us the exact sequence that causes issue
  • Expected vs actual behaviour. What you expected to happen vs what happened
  • Any error messages, giving us the exact text of any errors
  • Screenshots (if UI-related)
  • Audit logs, export and include if it is a data issue

We'll do our best to help you fix your issues.

Data Management
>