Troubleshooting and FAQ
Each heading below is a symptom or a question. Find yours, then read the cause and the fix.
Troubleshooting
The page says Ollama is unreachable
The banner reads Ollama is unreachable — answers are unavailable until it's back, and the status in the header says degraded. LocalRAG checks every 15 seconds.
- pip install: start Ollama (
ollama serve, or its system service), and check thatLOCALRAG_OLLAMA_URLpoints at it. The default ishttp://localhost:11434. - Docker: check that both containers are running with
docker compose ps, and start them withdocker compose up -d.
You can still add and delete documents while Ollama is down.
Answers are empty or fail
The model in LOCALRAG_MODEL may not be pulled into Ollama yet. Check with ollama list (or docker compose exec ollama ollama list). Pull it: ollama pull llama3.2, or docker compose exec ollama ollama pull llama3.2 under Docker.
The first answer is very slow
Ollama loads the model into memory on the first request after it starts, which can take a while on modest hardware. Later answers are faster. LocalRAG waits for the first word without timing out. A smaller model in LOCALRAG_MODEL answers faster.
The first upload takes a long time
The first document triggers the one-time download of the embedding model, about 130 MB. Later uploads only need the time to read and embed the file.
My PDF is rejected with no extractable text
The PDF is a scan or made of images, so it has no text layer, and LocalRAG has no OCR. Run it through an OCR tool that adds a text layer, then upload the result.
The whole upload was rejected
An upload from the browser or the API is all or nothing. If one file is unsupported (not .pdf, .txt or .md) or has no text, nothing is added. The message names the file. Remove it and upload the rest. The localrag ingest command skips bad files instead.
Every answer is I don't know
- Check that your documents are in the Documents list.
- Use the words your documents use. See Write questions that work well.
- Lower
LOCALRAG_SCORE_THRESHOLDa little, for example to0.25. See Configuration.
My documents disappeared after a restart
With pip, the data lives in data inside the folder where you started LocalRAG. Starting it from another folder uses a different, empty data folder. Start it from the same folder, or set LOCALRAG_DATA_DIR to a fixed path. Under Docker, docker compose down -v deletes the data volume.
The port is already in use
Another program uses port 8090. Set LOCALRAG_PORT to a free port, for example LOCALRAG_PORT=8091 localrag serve. Under Docker, change the left-hand number of the ports line in docker-compose.yml.
Questions
Does anything leave my computer?
Only two one-time downloads: the embedding model the first time you add a document, and whatever ollama pull fetches. After that LocalRAG makes no outgoing network calls, and can run with no network at all.
Can I use it from other computers on my network?
Yes, but think about who can reach it, because there is no login. The Docker setup already listens on all network connections. With pip, set LOCALRAG_HOST=0.0.0.0. Anyone who can reach the port can ask questions about your documents and delete them.
Does it remember the conversation?
No. Each question is answered on its own, from your documents.
Can it read Word documents or scanned PDFs?
Not in version 0.1.0. Only .pdf files with a text layer, .txt and .md.
Does it need a graphics card?
No. LocalRAG uses the CPU build of PyTorch for embeddings. Ollama runs on the CPU too, and can use a graphics card if you set one up for it.
How do I wipe everything?
Stop LocalRAG and delete the data folder (data by default), or run docker compose down -v under Docker. The second also deletes the Ollama models.
Where do I report a problem?
Open an issue on the LocalRAG issues page.