fss-mini-rag-github/docs/TROUBLESHOOTING.md

🛠️ Troubleshooting Guide - Common Issues & Solutions

Having problems? You're not alone! Here are solutions to the most common issues beginners encounter.

---

🚀 Installation & Setup Issues

❌ "Command not found: ollama"

Problem: The system can't find Ollama
Solution:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
# Or on Mac: brew install ollama
# Start Ollama
ollama serve

Alternative: Use the system without Ollama - it will automatically fall back to other embedding methods.

❌ "Permission denied" when running scripts

Problem: Script files aren't executable
Solution:

chmod +x rag-mini.py rag-tui.py install_mini_rag.sh
# Or run with python directly:
python3 rag-mini.py --help

❌ "Module not found" or import errors

Problem: Python dependencies not installed
Solution:

# Install dependencies
pip3 install -r requirements.txt
# If that fails, try:
pip3 install --user -r requirements.txt

❌ Installation script fails

Problem: ./install_mini_rag.sh doesn't work
Solution:

# Make it executable first
chmod +x install_mini_rag.sh
# Then run
./install_mini_rag.sh
# Or use proven manual method (100% reliable):
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt  # 2-8 minutes
.venv/bin/python -m pip install .                    # ~1 minute
source .venv/bin/activate
python3 -c "import mini_rag; print('✅ Installation successful')"

❌ Installation takes too long / times out

Problem: Installation seems stuck or takes forever
Expected Timing: 2-3 minutes fast internet, 5-10 minutes slow internet
Solutions:

1. Large dependencies are normal:

   • LanceDB: 36MB (vector database)
   • PyArrow: 43MB (data processing)
   • PyLance: 44MB (language parsing)
   • Total ~123MB + dependencies

2. For agents/CI/CD - run in background:

   ./install_mini_rag.sh --headless &
   # Monitor with: tail -f install.log
   

3. Check if installation is actually progressing:

   # Check pip cache (should be growing)
   du -sh ~/.cache/pip
   
   # Check if Python packages are installing
   ls -la .venv/lib/python*/site-packages/
   

4. Slow connection fallback:

   # Increase pip timeout
   .venv/bin/python -m pip install -r requirements.txt --timeout 1000
   

---

🔍 Search & Results Issues

❌ "No results found" for everything

Problem: Search isn't finding anything
Diagnosis & Solutions:

1. Check if project is indexed:

   ./rag-mini status /path/to/project
   # If not indexed:
   ./rag-mini index /path/to/project
   

2. Lower similarity threshold:

   • Edit config file, change similarity_threshold: 0.05
   • Or try: ./rag-mini search /path/to/project "query" --threshold 0.05

3. Try broader search terms:

   • Instead of: "getUserById"
   • Try: "user function" or "get user"

4. Enable query expansion:

   • Edit config: expand_queries: true
   • Or use TUI which enables it automatically

❌ Search results are irrelevant/weird

Problem: Getting results that don't match your search
Solutions:

1. Increase similarity threshold:

   search:
     similarity_threshold: 0.3  # Higher = more picky
   

2. Use more specific terms:

   • Instead of: "function"
   • Try: "login function" or "authentication method"

3. Check BM25 setting:

   search:
     enable_bm25: true  # Helps find exact word matches
   

❌ Search is too slow

Problem: Takes too long to get results
Solutions:

1. Disable query expansion:

   search:
     expand_queries: false
   

2. Reduce result limit:

   search:
     default_top_k: 5  # Instead of 10
   

3. Use faster embedding method:

   embedding:
     preferred_method: hash  # Fastest but lower quality
   

4. Smaller batch size:

   embedding:
     batch_size: 16  # Instead of 32
   

---

🤖 AI/LLM Issues

❌ "LLM synthesis unavailable"

Problem: AI explanations aren't working
Solutions:

1. Check Ollama is running:

   # In one terminal:
   ollama serve
   # In another:
   ollama list  # Should show installed models
   

2. Install a model:

   ollama pull qwen2.5:3b    # Good balance of speed and quality
   # Or: ollama pull qwen3:4b   # Larger but better quality
   

3. Test connection:

   curl http://localhost:11434/api/tags
   # Should return JSON with model list
   

❌ AI gives weird/wrong answers

Problem: LLM responses don't make sense
Solutions:

1. Lower temperature:

   llm:
     synthesis_temperature: 0.1  # More factual, less creative
   

2. Try different model:

   ollama pull qwen3:1.7b   # Recommended: excellent quality (default priority)
   ollama pull qwen3:0.6b   # Surprisingly good for CPU-only  
   ollama pull qwen3:4b     # Highest quality, slower
   

3. Use synthesis mode instead of exploration:

   ./rag-mini search /path "query" --synthesize
   # Instead of: ./rag-mini explore /path
   

---

💾 Memory & Performance Issues

❌ "Out of memory" or computer freezes during indexing

Problem: System runs out of RAM
Solutions:

1. Reduce batch size:

   embedding:
     batch_size: 8  # Much smaller batches
   

2. Lower streaming threshold:

   streaming:
     threshold_bytes: 512000  # 512KB instead of 1MB
   

3. Index smaller projects first:

   # Exclude large directories
   ./rag-mini index /path/to/project --exclude "node_modules/**,dist/**"
   

4. Use hash embeddings:

   embedding:
     preferred_method: hash  # Much less memory
   

❌ Indexing is extremely slow

Problem: Taking forever to index project
Solutions:

1. Exclude unnecessary files:

   files:
     exclude_patterns:
       - "node_modules/**"
       - ".git/**" 
       - "*.log"
       - "build/**"
       - "*.min.js"  # Minified files
   

2. Increase minimum file size:

   files:
     min_file_size: 200  # Skip tiny files
   

3. Use simpler chunking:

   chunking:
     strategy: fixed  # Faster than semantic
   

4. More workers (if you have good CPU):

   ./rag-mini index /path/to/project --workers 8
   

---

⚙️ Configuration Issues

❌ "Invalid configuration" errors

Problem: Config file has errors
Solutions:

1. Check YAML syntax:

   python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"
   

2. Copy from working example:

   cp examples/config.yaml .mini-rag/config.yaml
   

3. Reset to defaults:

   rm .mini-rag/config.yaml
   # System will recreate with defaults
   

❌ Changes to config aren't taking effect

Problem: Modified settings don't work
Solutions:

1. Restart TUI/CLI:

   • Configuration is loaded at startup
   • Exit and restart the interface

2. Check config location:

   # Project-specific config:
   /path/to/project/.mini-rag/config.yaml
   # Global config:
   ~/.mini-rag/config.yaml
   

3. Force re-index after config changes:

   ./rag-mini index /path/to/project --force
   

---

🖥️ Interface Issues

❌ TUI looks broken/garbled

Problem: Text interface isn't displaying correctly
Solutions:

1. Try different terminal:

   # Instead of basic terminal, try:
   # - iTerm2 (Mac)
   # - Windows Terminal (Windows)  
   # - GNOME Terminal (Linux)
   

2. Use CLI directly:

   ./rag-mini --help  # Skip TUI entirely
   

3. Check terminal size:

   # Make terminal window larger (TUI needs space)
   # At least 80x24 characters
   

❌ "Keyboard interrupt" or TUI crashes

Problem: Interface stops responding
Solutions:

1. Use Ctrl+C to exit cleanly:

   • Don't force-quit if possible

2. Check for conflicting processes:

   ps aux | grep rag-tui
   # Kill any stuck processes
   

3. Use CLI as fallback:

   ./rag-mini search /path/to/project "your query"
   

---

📁 File & Path Issues

❌ "Project not found" or "Permission denied"

Problem: Can't access project directory
Solutions:

1. Check path exists:

   ls -la /path/to/project
   

2. Check permissions:

   # Make sure you can read the directory
   chmod -R +r /path/to/project
   

3. Use absolute paths:

   # Instead of: ./rag-mini index ../my-project
   # Use: ./rag-mini index /full/path/to/my-project
   

❌ "No files found to index"

Problem: System doesn't see any files
Solutions:

1. Check include patterns:

   files:
     include_patterns:
       - "**/*.py"     # Only Python files
       - "**/*.js"     # Add JavaScript
       - "**/*.md"     # Add Markdown
   

2. Check exclude patterns:

   files:
     exclude_patterns: []  # Remove all exclusions temporarily
   

3. Lower minimum file size:

   files:
     min_file_size: 10  # Instead of 50
   

---

🔍 Quick Diagnostic Commands

Check system status:

./rag-mini status /path/to/project

Test embeddings:

python3 -c "from mini_rag.ollama_embeddings import OllamaEmbedder; e=OllamaEmbedder(); print(e.get_embedding_info())"

Verify installation:

python3 -c "import mini_rag; print('✅ RAG system installed')"

Test Ollama connection:

curl -s http://localhost:11434/api/tags | python3 -m json.tool

Check disk space:

df -h .mini-rag/  # Make sure you have space for index

---

🆘 When All Else Fails

1. Start fresh:

   rm -rf .mini-rag/
   ./rag-mini index /path/to/project
   

2. Use minimal config:

   # Simplest possible config:
   chunking:
     strategy: fixed
   embedding:  
     preferred_method: auto
   search:
     expand_queries: false
   

3. Try a tiny test project:

   mkdir test-project
   echo "def hello(): print('world')" > test-project/test.py
   ./rag-mini index test-project
   ./rag-mini search test-project "hello function"
   

4. Get help:

   • Check the main README.md
   • Look at examples/ directory
   • Try the basic_usage.py example

---

💡 Prevention Tips

For beginners:

• Start with default settings
• Use the TUI interface first
• Test with small projects initially
• Keep Ollama running in background

For better results:

• Be specific in search queries
• Use the glossary to understand terms
• Experiment with config settings on test projects first
• Use synthesis mode for quick answers, exploration for learning

Remember: This is a learning tool! Don't be afraid to experiment and try different settings. The worst thing that can happen is you delete the .mini-rag directory and start over. 🚀