Troubleshooting | Cine Power Planner

Troubleshooting

Troubleshooting Guide

This guide helps you resolve common issues with Cine Power Planner.

Everything here is something you can do from inside the app. It named build tooling — npm install, nvm, port 5173, hot reload — until 2026-09-07, which is advice you cannot follow: this guide is bundled into the app and read by people who have no checkout. If you are running the project from source, see setup.md in the developer documentation instead.

Table of Contents

Before You Start

  1. Check your browser — Chrome, Firefox, Safari or Edge, latest version
  2. Check your internet connection — required for the first load and for cloud sync; everything else works offline
  3. Reload the page — a hard reload (Cmd/Ctrl + Shift + R) clears a surprising number of issues
  4. Check your storage — Settings → Backup & Data → Storage reports whether IndexedDB and OPFS backup are available on this browser. That panel is the app's own answer; it beats guessing from a browser version number.

Gathering Information

Settings → Support → System Info collects your browser, version, platform and app version for you. Copy it into any bug report rather than assembling it by hand.

If you are filing manually, include:

  • Browser name and version
  • Operating system
  • Steps to reproduce
  • Expected vs actual behavior
  • Screenshots of errors
  • Console messages (F12 → Console)

The App Won't Load

Blank white screen

Symptoms: The page loads but stays white.

Solutions:

  1. Hard reload — Cmd/Ctrl + Shift + R
  2. Open the browser console (F12 → Console) and look for red errors
  3. Try a private / incognito window — this rules out an extension
  4. Disable browser extensions, especially content blockers and script blockers
  5. Ensure JavaScript is enabled

The app loads but looks unstyled or half-broken

Usually a partially-cached update.

  1. Hard reload (Cmd/Ctrl + Shift + R)
  2. Settings → Backup & Data → Cleanup → Clear Browser Cache — clears cached assets. You may need to sign in again.

Data Issues

Back up before you troubleshoot data. Settings → Backup & Data → Backup → Download full backup writes a .zip to your downloads folder. Do that first — several steps below replace data.

Data not saving

Symptoms: Changes disappear after refresh.

Solutions:

  1. Check storage is available

    • Settings → Backup & Data → Storage — IndexedDB must read Available
    • If it reads Unavailable, the browser is blocking site storage

  2. Check browser permissions

    • Allow cookies and site data for this site
    • Leave private/incognito mode — most browsers discard site storage when the window closes

  3. Check for JavaScript errors

    • Open the console (F12) and look for red messages

  4. Confirm a write lands

    • Settings → Backup & Data → Backup → Download full backup
    • Reload the page and check whether your data is still there

Data disappeared

Symptoms: All data is missing.

Solutions:

  1. Don't panic — check the on-device backups first:

    • Settings → Backup & Data → Auto Backups → Browse device backups opens the list of on-device snapshots so you can pick one.
    • The Restore from device backup button in the Backup section does not open a list. It immediately restores the most recent on-device backup and replaces your current data, so use it only when that is exactly what you want.

  2. Import a backup file:

    • Settings → Backup & Data → Backup → Import full backup
    • Pick the backup file you downloaded earlier
    • Imports merge into your current data rather than overwriting it

  3. Check the browser console (F12 → Console) for error messages

  4. Be careful with "clear browsing data" — clearing site data for this site deletes your local database. Download a backup first.

Backup import fails

Error: The backup won't restore, or shows errors.

Solutions:

  1. Check the file type. A full backup downloaded from this app is a .zip named cine-power-planner-backup-YYYY-MM-DD.zip — it contains the JSON plus your stored images. The importer also accepts a plain .json backup and a gzipped .json.gz.

    This guide told you to "ensure it's a valid JSON file" and to "open the JSON file in a text editor" until 2026-09-07. Doing that to the .zip the app itself produces shows binary noise and looks exactly like corruption. It is not — it is a ZIP archive, and it is the normal backup format.

  2. Check the file size. Imports are capped at 50 MB. A larger file is refused.

  3. Check the file isn't truncated — a download interrupted partway through produces a .zip that won't open in your OS file manager either. Re-download it.

  4. Check the console during the import (F12 → Console) for the specific error.

Device (OPFS) backup not working

Symptoms: The device backup option is unavailable or fails.

Solutions:

  1. Check whether this browser supports it

    • Settings → Backup & Data → Storage reports OPFS Backup: Available / Not available.
    • The app feature-detects this and writes a test file — it does not go by browser name or version, so that panel is authoritative for the browser you are actually using. This guide listed "Chrome 86+, Edge 86+, Opera 72+" until 2026-09-07 and omitted Safari and Firefox, both of which have supported it for years.

  2. Leave private / incognito mode — origin-private storage is typically unavailable there, which is the most common reason the panel reads Not available on a browser that otherwise supports it.

  3. Free up disk space — the write probe fails when the origin's quota is exhausted.

  4. Use downloaded backups instead — Settings → Backup & Data → Backup → Download full backup works on every browser and does not depend on OPFS.

PDF Export Issues

PDF won't download

Symptoms: Clicking export does nothing.

Solutions:

  1. Allow downloads and popups for this site in your browser settings
  2. Check your downloads folder — some browsers save without prompting
  3. Check the console (F12 → Console) for PDF generation errors
  4. Try a different browser

PDF generation fails

Error: A PDF error, or a blank PDF.

Solutions:

  1. Ensure the project has items — there must be something to export
  2. Check item data — items need names; remove items with missing required fields
  3. Try a smaller export — very large gear lists take longer and use more memory
  4. Try a different browser

PDF formatting issues

Symptoms: Text cut off, bad layout, missing items.

Solutions:

  1. Update your browser to the latest version
  2. Check for very long item names — these are the usual cause of overflow
  3. Try the export on a small test project to isolate whether it is data-specific
  4. Report it with sample data and browser info (Settings → Support → Bug Report)

PDF Tools Issues

PDF tool shows an error or doesn't load

Symptoms: Clicking a PDF tool shows an error or a blank content area.

Solutions:

  1. Reload the page and try again
  2. Ensure the input file is valid
    • Check the file is a real PDF and not corrupted
    • Some tools require specific PDF versions
  3. Check the file size
    • Very large PDFs (>100 MB) may exhaust browser memory
    • Split the file first
  4. Check the console (F12) for the specific error

PDF merge/split produces unexpected results

Solutions:

  1. Verify input files — all PDFs must be valid and not password-protected
  2. Check page ranges (for split) — the range must be within the total page count
  3. Try fewer files (for merge) — merge in batches if you have many

PDF encryption/decryption fails

Solutions:

  1. Check the password — passwords are case-sensitive, and trailing whitespace counts
  2. Verify the PDF format — some older PDFs don't support modern encryption
  3. Try a different encryption level if the tool offers one

💡 Note: All PDF tools run entirely offline. Your files never leave your device.

Scanner / Receipt OCR Issues

Applies to the Scan to PDF tool and the Accounting → Expenses capture surfaces. See Error Codes — Scanner / OCR Errors for the typed-error reference.

"OCR took too long" toast (timeout)

Symptoms: Form opens with empty fields; yellow toast saying "OCR took too long — fields can be entered manually."

Solutions:

  1. Enter fields manually — the attachment is preserved; the timeout is non-blocking.
  2. Tap "Run again" on the capture form to retry the OCR.
  3. Try a smaller / clearer scan — the per-page deadline is 12 s; long or low-contrast pages can exceed it.
  4. Close other browser tabs to free memory — the Tesseract worker is single-threaded and shares heap with the page.

"Password-protected PDFs can't be scanned" banner

Cause: The PDF requires a password. The app will never prompt for one (security policy).

Solutions:

  1. Decrypt locally first — use PDF Tools → Decrypt with your password, then re-upload the unprotected PDF.
  2. Open in Adobe Acrobat / Preview → Save As → uncheck password protection → re-upload.

"PDF has N pages — OCR processed pages 1-10" warning

Cause: Image-based PDFs with > 10 pages exceed the OCR fallback cap. Native-text PDFs are not capped — they extract in full.

Solutions:

  1. Split the PDF first — use PDF Tools → Split to break the file into ≤10-page chunks, then upload each separately as its own expense.
  2. Save as native-text PDF — re-print to PDF from the source application instead of scanning paper. Native-text extraction has no page cap.

"From cache" badge shows wrong text from a previous scan

Cause: The blob-hash OCR cache returned a stored result because the input file is byte-identical to a previous scan (within the last 30 days).

Solutions:

  1. Tap "Run again" below the form to force a fresh OCR — the cache is bypassed for this run.
  2. Re-take the photo or re-export the PDF — even a one-byte difference will miss the cache and trigger fresh OCR.

Camera permission denied

Symptoms: Scan opens but camera preview is blank, or the browser asks for permission repeatedly.

Solutions:

  1. Grant camera permission in the browser site settings (Chrome: Settings → Privacy → Site settings → Camera).
  2. On iOS Safari: the permission prompt only appears once per session. If you accidentally denied, go to Settings → Safari → Camera → Allow.
  3. On the installed mobile app (Capacitor): go to the OS settings (Settings → Cine Power Planner → Camera → Allow).
  4. Fall back to Upload — if the camera is unavailable, use the Upload flow with a phone-camera photo or scanned PDF.

Blank form after scan / upload — no fields pre-filled

Cause: OCR ran but couldn't extract any of the structured fields (vendor / amount / date / etc.). Common with very low-contrast thermal receipts or handwritten receipts.

Solutions:

  1. Fill the form manually — the attachment is still saved with the expense.
  2. Re-shoot with better lighting — thermal receipts especially benefit from indirect light + a flat surface.
  3. Crop tight to the printed area — extraneous background reduces OCR confidence.

Scanner stopped unexpectedly. Retry available.

Cause: The Tesseract worker terminated mid-recognition — usually memory pressure on older devices.

Solutions:

  1. Tap "Retry" in the banner.
  2. Close other browser tabs to free memory.
  3. Restart the browser if the crash recurs across multiple receipts.
  4. Use a smaller image — the practical limit is around 2048 × 2048 px for older phones.

Mobile Issues

App won't load on mobile

Solutions:

  1. Check internet connection (required for the first load)
  2. Reload the page
  3. Try a different browser (Chrome / Safari)
  4. Clear the mobile browser's cache

Touch gestures not working

Symptoms: Can't scroll, drag, or tap properly.

Solutions:

  1. Reload the page
  2. Update your browser
  3. Try landscape orientation — some dense tables are easier to hit there
  4. Report it with your device model (Settings → Support → Bug Report)

App doesn't fit the screen

Symptoms: Layout broken on mobile.

Solutions:

  1. Reload the page
  2. Reset page zoom to 100%
  3. Try landscape mode
  4. Report it with device model and browser

Install to home screen fails

Solutions:

  1. Check the browser

    • iOS: use Safari
    • Android: use Chrome

  2. Check PWA support — some browsers do not offer install

  3. Install manually — Chrome → Menu → Install Cine Power Planner

Browser-Specific Issues

Chrome

Solution: Update Chrome to the latest version.

Common fixes:

  • Clear the browser cache
  • Disable hardware acceleration if you see graphical glitches
  • Allow site data for the app

Firefox

Solution: Update Firefox to the latest version.

Common fixes:

  • Clear cookies and site data
  • Check Enhanced Tracking Protection — strict mode can block site storage
  • Disable resist-fingerprinting, which interferes with storage APIs

Safari

Solution: Update Safari and macOS/iOS.

Common fixes:

  • Check "Prevent cross-site tracking" if sign-in fails
  • Check iCloud Private Relay settings
  • Note that Safari discards site storage from private windows when they close

Edge

Solution: Update Edge to the latest version.

Common fixes:

  • Clear the browser cache
  • Check that IE mode is disabled
  • Disable hardware acceleration if needed

Cloud Sync Issues

Cloud sync is opt-in. If you have never signed in, none of this applies — your data is local and that is by design.

Sync stuck or failing

  1. Check your internet connection
  2. Verify you are signed in — Settings → Account
  3. Check the sync status badge in the sidebar
  4. Sign out and sign back in

Sync errors after the tab was idle

If sync errors appear after leaving a browser tab open for a long time:

  1. Reload the page — this triggers reconnection
  2. The app also reconnects on its own when the tab becomes visible again
  3. If errors persist, sign out and sign back in

Sync wedged and nothing helps

Settings → Backup & Data → Sync → Reset Sync clears all local sync state and re-syncs from scratch. Download a backup first.

Self-hosting the backend? CORS and 503 errors from your own Supabase deployment are an operator problem, not an app one — see the developer documentation.

Advanced Troubleshooting

Erasing everything and starting over

Warning: This deletes all local data.

Settings → Backup & Data → Factory Reset

Download a backup first — Settings → Backup & Data → Backup → Download full backup. Factory Reset is the app's own wipe; clearing site data in your browser does the same thing less cleanly and without a confirmation step.

Checking the browser console

  1. Open DevTools

    • Windows/Linux: F12 or Ctrl + Shift + I
    • macOS: Cmd + Option + I

  2. Go to the Console tab — look for red errors and copy the messages

  3. Check warnings too — yellow entries sometimes explain a failure

  4. Reload the page and watch for errors during load

Checking stored data directly

  1. Open DevTools (F12)
  2. Go to Application (Chrome/Edge) or Storage (Firefox)
  3. Expand IndexedDB
  4. Your data lives there

Settings → Backup & Data → Data Integrity does the same check from inside the app and can repair some problems it finds.

Reporting issues

Settings → Support → Bug Report submits a report from inside the app, and Settings → Support → System Info gives you the environment details to attach.

To file on GitHub instead:

  1. Check existing issues first — GitHub Issues
  2. Create a new issue with a clear title, what you were doing, expected vs actual behavior, steps to reproduce, your browser/OS, screenshots and any console errors

Common Error Messages

Error MessageWhat it meansWhat to do
QuotaExceededErrorThe browser's storage quota for this site is fullDownload a backup, then clear old auto-backups (Settings → Backup & Data → Cleanup)
SecurityErrorThe browser is blocking site storageAllow site data; leave private/incognito mode
NetworkErrorA request to the sync backend failedCheck your connection; retry. Local data is unaffected
NotAllowedErrorA permission was denied (camera, clipboard, downloads)Grant the permission in the browser's site settings
Import file is too largeThe backup exceeds the 50 MB import capImport a smaller backup, or a project-level backup instead

Still Having Issues?

  1. Report from inside the app: Settings → Support → Bug Report
  2. Search existing issues: GitHub Issues
  3. Create a new issue: Report Problem
  4. Include: browser and version, operating system, steps to reproduce, error messages, screenshots — Settings → Support → System Info collects most of this for you

Last Updated: 2026-09-07 Version: 0.790.2 ← Back to FAQ | Next: Help →