Troubleshooting

Concrete symptoms and what to do about them. If your problem isn't here, ask on GitHub Discussions or open an issue.

Signing in

The password reset email never arrives Check spam first. Reset mail can take a few minutes. If it still hasn't landed, email support@mail.scrapalot.app from the address you signed up with.

Signed out unexpectedly Sessions expire, and signing in on another device can end an old session. Sign in again. If it repeats within minutes, your browser is likely blocking storage for the site — check that cookies and site data are allowed for scrapalot.app.

The desktop app won't complete browser sign-in The app registers a scrapalot:// handler that the browser hands the session back through. Two things break it:

• The app is running directly from the mounted .dmg on macOS. Drag it out to ~/Applications (or anywhere) and launch it from there.
• Your browser blocked the "open this app?" prompt. Retry and allow it.

Uploading and processing

A document never starts processing Check whether it is Deferred. Files over 20 MB, PDFs over 1,000 pages and scanned PDFs wait for confirmation — click Process all on the banner in the Upload tab. Files that show "Waiting to compose" need Compose.

A document is stuck in "Processing" Give it time proportional to the work: scanned PDFs go through OCR page by page, and audio/video are transcribed before anything else happens. A 400-page scanned book can take many minutes.

A document shows "Failed" The reason is shown next to it. Most failures — a stalled worker, a time limit, an interrupted entity extraction — can be retried with Retry processing. "Source file no longer on disk" needs the file uploaded again; "DRM-protected" and "no extractable text" mean the file itself cannot be read. See Uploading Documents.

If it hasn't moved in half an hour, note the document name and size and report it. Self-hosting? Check the worker logs:

docker compose logs workers

The upload is rejected Check the extension against the supported formats and the 200 MB per-file limit. The most common surprise is .doc — only .docx is supported, so convert first. "Already exists" means the same file is already in that collection.

A scanned PDF gives poor answers OCR quality is the ceiling on answer quality. If the scan is skewed, low-resolution, or a photograph of a page, the extracted text will be noisy and retrieval will suffer. A cleaner copy of the same document is worth more than any setting change.

Storage quota reached Delete documents you no longer need, or move up a tier — see Pricing. Your usage is shown in Settings → Account. In the desktop app you can also keep original files on your own computer instead (Settings → Account → Where your books are kept).

"LLM quota exhausted" You have used up your plan's monthly AI tokens, or your own provider key has run out of credit. Wait for the monthly reset, upgrade, or add credit / switch provider under Settings → AI Providers.

Answers

"No sources found" or an answer with no citations The retriever found nothing relevant. Usually one of:

• The question is too broad. "What are the main themes?" over 500 documents has no single answer to retrieve. Narrow to one collection or document.
• The document has no text layer. A scanned PDF that failed OCR contains images, not words. Check whether the document preview shows selectable text.
• The wrong collection is selected. Check the Knowledge Stacks button in the chat toolbar, or @-mention the document you mean.

Answers are generic, or ignore my documents Confirm that a collection or document is actually selected — with nothing selected, the chat answers from the model's general knowledge. Citations are the tell: no citations means no grounding. In manual mode, setting Knowledge augmentation to Strict keeps answers to your cited sources.

A mode or setting I expected is missingSimple mode (Settings → General) hides advanced options such as model settings, prompt templates, the tutor and thought-partner modes, and the Integrations, AI Providers and Prompts tabs. Turn it off to see them.

A feature is greyed out or returns "upgrade required" It belongs to a higher plan. See Pricing.

Streaming stops halfway through a long answer Usually a proxy or network timeout between you and the app, most often on a corporate VPN. Retry; if it reproduces consistently on one network, that network is the cause.

Desktop app

The Local AI tab only shows a hardware card The app's local AI engine is still starting, or this platform build doesn't include it yet. The tab upgrades itself as soon as the engine is up — reopen it after a minute, or restart the app.

I'm signed in as a guest Guest work stays on that computer and has no access to the bundled Scrapalot AI models. Sign in from Settings → Account → Sign in with your account.

Notes

Changes don't appear in the other tab The notes editor syncs over its own WebSocket and takes a few seconds. If it doesn't converge, reload both tabs — the document is stored server-side, so nothing is lost.

Self-hosted (Community Edition)

A container won't start

docker compose ps          # which service is unhealthy
docker compose logs chat   # or: backend, gw, ui, pgvector, redis

"Connection to database failed" Almost always POSTGRES_PASSWORD in .env changed after the volume was created — Postgres keeps the password from initialization.

docker compose logs pgvector

# Either restore the original password in .env, or start clean (destroys data):
docker compose down -v && docker compose up -d --build

Port already in use

sudo lsof -i :3000   # also 8080, 8090, 8091, 15432, 6379

Change the host-side port mapping in docker-compose.yml and bring the stack back up.

The UI loads but every request fails The UI talks to the gateway, never to the backends directly. Check the gateway first: docker compose logs gw.

Answers come back empty No LLM key configured, or the provider rejected it. docker compose logs chat will show the authentication error. Verify the key in .env and in Settings → AI Providers.

Everything is slow Document processing is CPU-heavy. Give Docker at least 8 GB of RAM, and expect embedding and OCR to compete with everything else while a large batch is ingesting.

Getting more help

When reporting a problem, include:

1. What you did — the steps that led to it
2. What happened — the exact error text, and a screenshot if it's visual
3. Where — web, desktop or Android, and the app version (desktop: Help → About)

• GitHub Discussions — questions and self-hosting help
• Discord — real-time community chat
• GitHub Issues — bug reports
• support@mail.scrapalot.app — account and billing