Repository navigation
Troubleshooting
Symptom: ConnectionRefusedError or Error: connect ECONNREFUSED 127.0.0.1:11434
Fix: Start Ollama in a separate terminal:
ollama serveVerify it is running:
curl http://localhost:11434Symptom: ModuleNotFoundError: No module named 'chromadb' (or any other package)
Fix: The virtual environment is not activated, or dependencies are not installed:
source rag_env_311/bin/activate
pip install -r requirements.txtSymptom: InvalidArgumentError: Collection expecting embedding with dimension of X, got Y
Fix: The ChromaDB collection was built with a different embedding model. Delete it and rebuild:
rm -rf ./chroma_db/
streamlit run app.pySymptom: "No supported documents found" on startup, or "I could not find relevant information" for every query.
Fix:
- Verify files are under
./docs/with a supported extension (.pdf,.txt,.docx,.xlsx,.xls,.pptx,.csv,.md,.html) - Check the terminal output for
[ERROR]lines during loading - If using the web UI, confirm the chunk count in the sidebar is greater than 0
Symptom: Queries take 30–60+ seconds to respond.
Fix options:
- Close other applications to free RAM
- Use the live demo on Hugging Face (runs on cloud GPU)
- Reduce
TOP_RETRIEVEandTOP_RERANKinsrc/rag/config.py(fewer chunks = faster reranking)
Symptom: "Added 0 chunks" after pasting a URL.
Fix:
- Verify the URL is publicly accessible (no login required)
- Check that the page is not behind a JavaScript-rendered SPA — the system fetches raw HTML only
- For PDFs, ensure the URL ends in
.pdfor the server returnsContent-Type: application/pdf
Symptom: Pages from external domains appear in the index after a recursive crawl.
Fix: This should not happen — the crawler is restricted to the same domain as the seed URL. If it does occur, open an issue with the seed URL.
Symptom: The browser shows a blank page or a Streamlit traceback.
Fix:
# Kill any existing Streamlit process
pkill -f streamlit
# Clear the Streamlit cache
rm -rf ~/.streamlit/
# Restart
streamlit run app.pyIf none of the above resolves your issue, open an issue on GitHub with:
- The exact error message (copy the full traceback)
- Your operating system and Python version (
python --version) - The output of
pip list | grep -E 'chromadb|ollama|streamlit'