1097 Troubleshooting A7a910a2

# Troubleshooting Guide

This guide covers common issues and their solutions.

## Table of Contents

- [LLM Connection Issues](#llm-connection-issues)
- [Search Engine Issues](#search-engine-issues)
- [Rate Limiting](#rate-limiting)
- [Database Issues](#database-issues)
- [WebSocket/Real-time Updates](#websocketreal-time-updates)
- [Docker Issues](#docker-issues)
- [API Issues](#api-issues)
- [Performance Issues](#performance-issues)

---

## LLM Connection Issues

### Ollama Not Connecting

**Symptoms:**
- "Failed to connect to Ollama"
- "Connection refused" errors
- Empty responses from LLM

**Solutions:**

1. **Verify Ollama is running:**
   ```bash
   curl http://localhost:11434/api/tags
   ```

2. **Check the URL configuration:**
   - Default: `http://localhost:11434`
   - For Docker: Use `http://host.docker.internal:11434` or your host IP
   - Settings location: `llm.ollama.url`

3. **Verify the model is pulled:**
   ```bash
   ollama list
   ollama pull llama3.2
   ```

4. **Check Docker networking:**
   ```bash
   # If running LDR in Docker, Ollama on host:
   docker run --add-host=host.docker.internal:host-gateway ...
   ```

### OpenAI API Errors

**Symptoms:**
- "Invalid API key"
- "Rate limit exceeded"
- "Model not found"

**Solutions:**

1. **Verify API key format:**
   - Should start with `sk-`
   - Check for leading/trailing whitespace

2. **Check API key permissions:**
   - Ensure key has access to the model you're using
   - Verify organization ID if using org-scoped keys

3. **Rate limits:**
   - Wait and retry for rate limit errors
   - Consider using a higher tier API key
   - Reduce `questions_per_iteration` setting

4. **Model availability:**
   - Verify model name is correct (e.g., `gpt-4`, not `gpt4`)
   - Check if model is available in your region

### OpenRouter Issues

**Symptoms:**
- Authentication failures
- Model not available

**Solutions:**

1. **API key format:**
   ```
   # Settings
   llm.openrouter.api_key = <your-key-here>
   ```

2. **Model naming:**
   - Use full model paths: `anthropic/claude-3-opus`
   - Check available models at openrouter.ai/docs

---

## Search Engine Issues

### DuckDuckGo Returning No Results

**Symptoms:**
- Empty search results
- "No results found" consistently

**Solutions:**

1. **Rate limiting:** DuckDuckGo aggressively rate limits. Solutions:
   - Switch to SearXNG or another engine
   - Increase wait time in rate limiting settings
   - Use `search.rate_limiting.profile = conservative`

2. **Check network:** Verify you can access DuckDuckGo directly

3. **Try alternative engines:**
   ```python
   # In settings
   search.tool = "searxng"  # or "brave", "tavily", etc.
   ```

### SearXNG Setup Issues

**Symptoms:**
- "Connection refused"
- "404 Not Found"

**Solutions:**

1. **Verify SearXNG is running:**
   ```bash
   curl http://localhost:8080/search?q=test&format=json
   ```

2. **Check URL configuration:**
   ```
   search.engine.searxng.url = http://localhost:8080
   ```

3. **Ensure JSON format is enabled** in SearXNG settings

4. **Docker networking:** Same as Ollama - use proper host references

### API Key Issues for Search Engines

**Symptoms:**
- "API key required"
- "Unauthorized" errors

**Solutions:**

1. **Verify key is set:**
   - Check in Settings > Search > [Engine Name]
   - Or via environment variable

2. **Engine-specific settings:**
   | Engine | Setting Key |
   |--------|-------------|
   | Brave | `search.engine.brave.api_key` |
   | Tavily | `search.engine.tavily.api_key` |
   | Serper | `search.engine.serper.api_key` |
   | SerpAPI | `search.engine.serpapi.api_key` |

---

## Rate Limiting

### "Rate limit exceeded" Errors

**Symptoms:**
- Searches failing with rate limit errors
- Long waits between searches
- Inconsistent search performance

**Solutions:**

1. **View current rate limit status:**
   ```bash
   python -m local_deep_research.web_search_engines.rate_limiting status
   ```

2. **Reset rate limits for an engine:**
   ```bash
   python -m local_deep_research.web_search_engines.rate_limiting reset --engine duckduckgo
   ```

3. **Adjust rate limiting profile:**
   ```
   # Options: conservative, balanced, aggressive
   search.rate_limiting.profile = conservative
   ```

4. **Use multiple search engines** to distribute load:
   ```
   search.tool = auto  # Automatically selects engines
   ```

### Rate Limiting CLI Commands

```bash
# View status
python -m local_deep_research.web_search_engines.rate_limiting status
python -m local_deep_research.web_search_engines.rate_limiting status --engine arxiv

# Reset learned rates
python -m local_deep_research.web_search_engines.rate_limiting reset --engine duckduckgo

# Clean old data
python -m local_deep_research.web_search_engines.rate_limiting cleanup --days 30

# Export data
python -m local_deep_research.web_search_engines.rate_limiting export --format csv
```

---

## Database Issues

### "Database is locked" Errors

**Symptoms:**
- SQLite lock errors
- Operations timing out
- Concurrent access failures

**This is likely a bug.** If you encounter persistent "database is locked" errors, please:

1. **Collect logs:**
   - Check the application logs for error details
   - Note what action triggered the error

2. **Report the issue:**
   - Open an issue at [GitHub Issues](https://github.com/LearningCircuit/local-deep-research/issues)
   - Include the logs and steps to reproduce

**Temporary workarounds:**

1. **Check for zombie processes:**
   ```bash
   ps aux | grep python
   # Kill any stuck LDR processes
   ```

2. **Restart the application** to release any held locks

### Encryption/SQLCipher Issues

**Symptoms:**
- "file is not a database"
- "database disk image is malformed"
- Cannot open user database

**Solutions:**

1. **Verify SQLCipher is installed:**
   ```bash
   pip show sqlcipher3-binary
   ```

2. **Check password/key:**
   - User databases are encrypted with derived keys
   - Password changes require re-encryption

3. **For corrupted databases:**
   - Check `~/.local/share/local-deep-research/users/` for backups
   - Consider creating a new user account

4. **Integrity check:**
   - Use the `/auth/integrity-check` endpoint
   - Or run manual SQLite integrity checks

### Migration Issues

**Symptoms:**
- Schema version mismatch
- Missing tables or columns

**Solutions:**

1. **Check version:**
   ```python
   from local_deep_research import __version__
   print(__version__)
   ```

2. **Run migrations** (if applicable):
   - Migrations are typically automatic on startup
   - Check logs for migration errors

---

## WebSocket/Real-time Updates

### Progress Updates Not Showing

**Symptoms:**
- Research starts but no progress shown
- UI appears stuck
- Results appear suddenly at end

**Solutions:**

1. **Check browser console** for WebSocket errors

2. **Verify SocketIO connection:**
   - Open browser DevTools > Network > WS
   - Look for `/socket.io` connections

3. **Firewall/proxy issues:**
   - WebSocket needs persistent connections
   - Some proxies don't support WebSocket
   - Try direct connection (no proxy)

4. **Fallback to polling:**
   - The client automatically falls back to HTTP polling
   - Check if polling requests are working

### Connection Drops

**Symptoms:**
- Frequent disconnections
- "transport close" errors

**Solutions:**

1. **Check network stability**

2. **Adjust timeout settings:**
   - Default ping timeout: 20 seconds
   - Default ping interval: 5 seconds

3. **For reverse proxy setups:**
   ```nginx
   # Nginx example
   location /socket.io {
       proxy_pass http://localhost:5000;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_set_header Host $host;
       proxy_read_timeout 86400;
   }
   ```

---

## Docker Issues

### Container Won't Start

**Symptoms:**
- Container exits immediately
- "exec format error"
- Port already in use

**Solutions:**

1. **Check logs:**
   ```bash
   docker logs local-deep-research
   ```

2. **Port conflicts:**
   ```bash
   # Check what's using port 5000
   lsof -i :5000

   # Use different port
   docker run -p 8080:5000 ...
   ```

3. **Architecture mismatch:**
   - Ensure image matches your CPU architecture (amd64/arm64)

### GPU Not Working

**Symptoms:**
- Ollama running on CPU instead of GPU
- "CUDA not available"

**Solutions:**

1. **Use GPU-specific compose file:**
   ```bash
   docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml up
   ```

2. **Verify NVIDIA runtime:**
   ```bash
   docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi
   ```

3. **Install nvidia-container-toolkit:**
   ```bash
   # Ubuntu/Debian
   sudo apt-get install -y nvidia-container-toolkit
   sudo systemctl restart docker
   ```

### Volume/Permission Issues

**Symptoms:**
- "Permission denied" errors
- Data not persisting

**Solutions:**

1. **Check volume ownership:**
   ```bash
   ls -la ~/.local/share/local-deep-research/
   ```

2. **Fix permissions:**
   ```bash
   sudo chown -R $(id -u):$(id -g) ~/.local/share/local-deep-research/
   ```

---

## API Issues

### CSRF Token Errors

**Symptoms:**
- "CSRF token missing"
- "CSRF validation failed"

**Solutions:**

1. **Fetch token before requests:**
   ```python
   # Get CSRF token from server
   resp = session.get("http://localhost:5000/auth/csrf-token")
   csrf = resp.json()["csrf_token"]

   # Include in requests
   session.post(
       "http://localhost:5000/api/v1/quick_summary",
       json={"query": "..."},
       headers={"X-CSRFToken": csrf}
   )
   ```

2. **Use the LDRClient** which handles CSRF automatically:
   ```python
   from local_deep_research.api.client import LDRClient

   with LDRClient() as client:
       client.login(username, password)
       result = client.quick_research("query")
   ```

### Authentication Failures

**Symptoms:**
- "Login required"
- Session expires unexpectedly

**Solutions:**

1. **Verify credentials:**
   - Username is case-sensitive
   - Check for password special characters

2. **Session issues:**
   - Clear cookies and re-login
   - Check session timeout settings

3. **For API access:**
   - Consider using API keys instead of sessions
   - Check `api.enabled` setting

---

## Performance Issues

### Slow Research

**Symptoms:**
- Research taking too long
- High memory usage
- Timeouts

**Solutions:**

1. **Reduce iterations:**
   ```
   search.iterations = 2  # Instead of default 4
   ```

2. **Reduce questions per iteration:**
   ```
   search.questions_per_iteration = 3  # Instead of 5
   ```

3. **Use faster strategy:**
   ```
   search.strategy = rapid  # Instead of source-based
   ```

4. **Limit search results:**
   ```
   search.max_results = 5  # Instead of 10
   ```

5. **Use snippet-only mode:**
   ```
   search.snippets_only = true  # Skip full content retrieval
   ```

### Memory Issues

**Symptoms:**
- Out of memory errors
- System becomes unresponsive

**Solutions:**

1. **Limit concurrent research:**
   - Reduce queue size
   - Wait for research to complete before starting new ones

2. **Use smaller models:**
   - `llama3.2:3b` instead of larger variants
   - Quantized models (Q4, Q5)

3. **Increase swap space** (Linux):
   ```bash
   sudo fallocate -l 8G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   ```

---

## Getting Help

If you're still experiencing issues:

1. **Check logs:**
   - Console output
   - `~/.local/share/local-deep-research/logs/`

2. **Search existing issues:**
   - [GitHub Issues](https://github.com/LearningCircuit/local-deep-research/issues)

3. **Create a new issue** with:
   - LDR version
   - Operating system
   - Docker/native installation
   - Steps to reproduce
   - Relevant logs

---

## See Also

- [Architecture Overview](./architecture/OVERVIEW.md) - System architecture
- [FAQ](./faq.md) - Frequently asked questions
- [Search Engines Guide](./search-engines.md) - Detailed engine documentation