When to read this
An upload failed and you're trying to figure out why. Maybe you got a specific error message; maybe the upload just silently didn't produce a document. This article walks through the common error messages and what to do about each, plus diagnostic steps for the silent cases.
For the broader file-format reference (what's accepted and what isn't), see supported file types and sizes. For extraction-after-upload problems (the file uploaded but the AI got it wrong), see the OCR extracted the wrong fields.
Step 1 — check the error message first
The upload dialog and the Documents list both show what happened. The most common errors and their fixes:
| Error | What it means | First fix |
|---|---|---|
Invalid file type |
Renamed file, or unsupported format | Re-export as PDF/JPG/PNG/HEIC |
File too large |
Over 20 MB | Compress, re-save at lower resolution, or split into pages |
Monthly quota reached |
At plan limit | Upgrade plan or wait for the 1st-of-month reset |
Virus scanner blocked |
ClamAV flagged the file | Check the file locally; if it's a false positive, write to support |
Encryption setup pending |
Account-key not yet provisioned (very rare, brand-new accounts) | Wait 30 seconds, retry |
Connection lost |
Network blip mid-upload | Just retry — most uploads recover |
Content sniffing failed |
File's claimed type doesn't match its bytes | Re-export from the source application |
Encrypted PDF |
PDF requires a password to open | Decrypt + re-save without password |
Each error has a one-line explanation right below the message in the UI. The table here is the canonical lookup.
Step 2 — if you get no error message at all
Sometimes uploads silently fail — the progress bar disappears but no document appears in the list. Run these diagnostics in order:
Check your monthly counter
Settings → Billing → Usage this month. If you're at 100% (e.g. 30/30 on Starter), the UI usually shows a banner, but in rare cases the banner is hidden by browser zoom level or by an aggressive ad-blocker. The hard cap on uploads is the most common silent failure.
Open the browser DevTools
F12 (or Cmd+Option+I on macOS) opens DevTools. Switch to the Console tab and try the upload again. Look for red error lines containing POST /api/documents/ — the response body usually has a specific error code. Common ones:
413 Payload Too Large— file size cap, even if the UI didn't say so415 Unsupported Media Type— content-type rejection429 Too Many Requests— rate limit hit (rare on uploads but possible during bulk batch)500 Internal Server Error— server-side issue (write to support with the timestamp)
Try a different file
Test with a known-good small file (a 100 KB PDF you know works — keep one in your testing folder). If the small PDF goes through cleanly, the failing file has a specific issue (encoding, encryption, malformation). If even the small PDF fails, the issue is on your client side (browser extension, VPN, network).
Try a different browser
Some browser extensions interfere with multipart uploads — most often ad-blockers (uBlock Origin with strict mode), privacy extensions (Brave Shields with everything turned up, Tor Browser), and corporate VPN proxies. Quick test: open an incognito / private window (extensions are usually disabled there) and try the same upload. If it works in incognito, an extension is the cause.
Check for malicious-software interference
Rare, but corporate security tools sometimes intercept browser uploads (especially on Windows with proxy-based scanning). If you're on a corporate device and uploads consistently fail, ask your IT team about endpoint security tools that scan uploads — they sometimes need a specific allow-list rule for app.taxiteasy.org.
Common edge-case failures
Drag from email client straight to browser
Often doesn't pass the file metadata correctly — the dragged file might be an "alias" or "shortcut" rather than the actual file. Save the attachment to your Downloads folder first, then drag from Finder / Explorer to the browser. Workaround: drag from email → desktop → browser, instead of email → browser directly.
Files from cloud storage (iCloud Drive, Google Drive, Dropbox) on macOS
macOS may delay downloading the actual file content if the file is marked as "online only" or "available on demand". Symptom: the upload starts, hangs at 0%, eventually fails. Fix: right-click the file in Finder → Download Now (iCloud) or Make Available Offline (Drive / Dropbox) — wait for the download icon to clear, then upload.
Files synced from Dropbox
Same as iCloud Drive on macOS. Dropbox marks files as "online-only" by default on slow connections; uploading-an-online-only-file is a multi-step download-then-upload that often fails silently. Force the download first.
HEIC photos from iPhone
Some browsers don't pass HEIC correctly in drag-and-drop. Workaround: open Photos on your iPhone, Share → Save to Files → On My iPhone to copy the photo to local storage; then upload from there. Or convert HEIC to JPG via the Files app first.
Alternative: change iPhone's camera setting to Most Compatible (Settings → Camera → Formats → Most Compatible) so future photos are JPG by default. Existing HEIC photos stay HEIC.
Scans from MFP / network printer
Multifunction printers and network scanners often produce PDFs with embedded JBIG2 compression that some browsers / extractors don't handle cleanly. Symptom: PDF uploads but extraction fails with "could not parse PDF". Fix: open the scanner PDF in any PDF viewer (Preview / Adobe Reader / Skim), File → Export to PDF (or Save As → PDF) to re-encode in standard PDF. The re-encoded version uploads cleanly.
Files with extremely long filenames
Some servers truncate at 255 characters; on Windows the limit is often 260 path characters. Symptom: upload succeeds but the document detail page shows a partial filename or empty. Fix: rename the file to something shorter before uploading.
Multi-page PDF where only page 1 extracts
Different problem from upload failing — see the OCR extracted the wrong fields. Re-saving the PDF in a viewer often resolves it.
If nothing works
Write to [email protected] with subject [BUG] Upload failing. Include:
- The error message (screenshot if helpful — copy-paste the text if no screenshot tool)
- The file's size and type (right-click → Get Info on macOS, or Properties on Windows)
- Your browser and OS (e.g. "Chrome 125 on macOS 14.5")
- What you've tried (incognito mode, different file, different browser, restart)
- The approximate timestamp of the failed attempt (helps us match server logs)
We typically reply within 1–3 working days. For urgent end-of-month uploads where you're approaching a tax-filing deadline, mark the subject [BUG][URGENT] and we prioritise.
Edge cases
Upload counter went up but the document doesn't appear. The file passed size check but failed content scan or virus scan after the counter incremented. The document doesn't count against your quota in this case — refresh the Documents page after a minute and the counter will reconcile. If the counter stays high but no document appears, it's a UI cache issue; hard-refresh (Cmd+Shift+R / Ctrl+Shift+R) clears it.
Browser says "upload complete" but the document never appears. Some browsers report 100% on the HTTP request before the server actually finishes processing. If the document doesn't appear after 2–3 minutes, check Documents → Show all including hidden — sometimes a failed extraction is auto-hidden but the upload itself succeeded.
Upload works on one network but not another. Some corporate firewalls block multipart POST requests above a certain size. If you have a 15 MB PDF that uploads on home Wi-Fi but fails on office Wi-Fi, the corporate firewall is the cause. Talk to IT, or upload from home / mobile data.
I'm trying to upload via the API. API uploads have the same constraints as UI uploads (format, size, content-sniffing). If you're getting failures on a programmatic upload, the API response body includes a specific error code; match against the table above.
Upload is stuck at 99% indefinitely. The TLS connection is open but the server didn't acknowledge completion. Most often a transient network issue; close the upload, try again. If it happens repeatedly with the same file, see if the file is the issue (try a known-good small file to rule out general network).
Drag-and-drop overlay doesn't appear. Firefox with strict mode and Brave with Shields Up sometimes suppress the file-drag-enter event. Either lower the shield for app.taxiteasy.org or use the Upload button on the Documents page — same end result.
I want to upload a folder. Browser file pickers don't have a "pick folder" option for security reasons. Open the folder, select all files inside (Cmd+A / Ctrl+A), and drag the selection. Multi-select-then-drag works in all browsers.
My phone uploads fail but desktop uploads work. Most often: mobile network is slow / unstable. Try over Wi-Fi. Also check that the phone hasn't muted the upload via "low data mode" or "data saver" — both suppress background-tab uploads in some browsers.
Related
- Supported file types and sizes — what passes intake
- Upload via the web — the normal upload flow
- Understanding your document counter — quota that drives "monthly quota reached" errors
- The OCR extracted the wrong fields — when upload succeeded but extraction is wrong