Troubleshooting failed uploads

Diagnose stalled uploads, OCR errors, and ingestion failures with this step-by-step checklist.

May 21, 2026

If an upload stalls or an ingest job ends in Failed, this guide walks through the most common causes.

1. Check the job status panel

Open Uploads → Processing in the sidebar. Each job shows a status:

  • Queued. Upload finished; waiting for a worker.
  • Processing. OCR, structuring, and embedding are running.
  • Processed / pending review. Awaiting review before publishing.
  • Completed. Done — the document is in your Library.
  • Error. Something went wrong. Click the row for a human-readable error message.

The failure reason almost always tells you exactly what to fix.

2. Re-upload after checking the file

Most upload failures fall into one of these buckets:

  • Unsupported format. See Supported file formats. Convert with a free tool and retry.
  • Encrypted / password-protected PDF. Remove the password (Acrobat, Preview on macOS, or qpdf --decrypt), then re-upload.
  • Corrupted file. Open the file locally first. If your PDF viewer can't read it, Vulgate can't either. Re-export from the source.
  • Empty or all-image PDF with no contrast. OCR needs at least some legible content. Raise the contrast in a tool like Acrobat or Preview, then retry.
  • Audio file with no audible content. A few seconds of silence is fine, but a full file of silence will fail.

3. Browser-side stalls

If the Uploading progress bar gets stuck partway:

  • Network drop. Refresh the page — Vulgate resumes the upload from where it left off for files using multipart upload.
  • Browser extension interference. Try an Incognito / Private window with extensions disabled.
  • Corporate proxy blocking storage. Vulgate uploads files to Cloudflare R2 via a signed URL (S3-compatible API); some corporate proxies block direct-to-storage traffic. Try a different network or contact your IT team.

4. Spend cap reached

If the job says You have exceeded your spend cap for your plan, you've used your plan's monthly ingestion credits. Wait until the next billing cycle, or open Settings → Billing and upgrade to a higher tier. See Adjusting your plan.

5. Audio transcription specifically

  • Language mismatch. Vulgate auto-detects language; if your file is multilingual, results may suffer. Split the file by language and re-upload.
  • Silent audio. Verify the file plays audibly locally first.
  • Very long file. Files over two hours sometimes time out. Split into chunks (ffmpeg -i input.mp3 -f segment -segment_time 3600 -c copy chunk_%03d.mp3) and re-upload.

See Why audio transcription failed for deeper debugging.

6. Still stuck?

If none of the above helps, please email us at info@vulgate.ai with:

  • The Job ID from the failed row (the UUID shown in the jobs table).
  • The original filename.
  • A copy of the file, if you can share it.

We'll dig into the logs and respond within one business day.

Search help