local-deep-research/docs/faq.md

# Frequently Asked Questions (FAQ)

> **Note**: This documentation is maintained by the community and may contain inaccuracies. While we strive to keep it up-to-date, please verify critical information and report any errors via [GitHub Issues](https://github.com/LearningCircuit/local-deep-research/issues).

## Table of Contents

1. [General Questions](#general-questions)
2. [Installation & Setup](#installation--setup)
3. [Configuration](#configuration)
4. [Common Errors](#common-errors)
5. [Search Engines](#search-engines)
6. [LLM Configuration](#llm-configuration)
7. [Local Document Search](#local-document-search)
8. [Performance & Optimization](#performance--optimization)
9. [Docker Issues](#docker-issues)
10. [Platform-Specific Issues](#platform-specific-issues)

## General Questions

### What is Local Deep Research (LDR)?

LDR is an open-source AI research assistant that performs systematic research by breaking down complex questions, searching multiple sources in parallel, and creating comprehensive reports with proper citations. It can run entirely locally for complete privacy.

### How is LDR different from ChatGPT or other AI assistants?

LDR focuses specifically on research with real-time information retrieval. Key differences:
- Provides citations and sources for claims
- Searches multiple databases including academic papers
- Can run completely offline with local models
- Open source and customizable
- Searches your own documents

### Is LDR really free?

Yes! LDR is open source (MIT license). Costs only apply if you:
- Use cloud LLM providers (OpenAI, Anthropic)
- Use premium search APIs (Tavily, SerpAPI)
- Need cloud hosting infrastructure

Local models (Ollama) and free search engines have no costs.

### Can I use LDR completely offline?

Partially. You can:
- Use local LLMs (Ollama) offline
- Search local documents offline
- But web search requires internet

For intranet/offline environments, configure LDR to use only local documents and disable web search.

## Installation & Setup

### What are the system requirements?

- **Python**: 3.10 or newer
- **RAM**: 8GB minimum (16GB recommended for larger models)
- **GPU VRAM** (for Ollama):
  - 7B models: 4GB VRAM minimum
  - 13B models: 8GB VRAM minimum
  - 30B models: 16GB VRAM minimum
  - 70B models: 48GB VRAM minimum
- **Disk Space**:
  - 100MB for LDR
  - 1-2GB for SearXNG
  - 5-15GB per Ollama model
- **OS**: Windows, macOS, Linux

### Do I need Docker?

Docker is recommended but not required. You can:
- Use Docker Compose (easiest)
- Use Docker containers individually
- Install via pip without Docker

### Which installation method should I use?

- **Docker Compose**: Best for production use
- **Docker**: Good for quick testing
- **Pip package**: Best for development or Python integration

### How do I set up SearXNG?

SearXNG is a privacy-respecting metasearch engine. Learn more at the [SearXNG repository](https://github.com/searxng/searxng).

```bash
docker pull searxng/searxng
docker run -d -p 8080:8080 --name searxng searxng/searxng
```

Then set the URL to `http://localhost:8080` in LDR settings.

### The cookiecutter command fails on Windows

For Windows users, you can use the generated docker-compose file directly instead of running cookiecutter:
```yaml
services:
  local-deep-research:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "5000:5000"
    environment:
      - SEARXNG_URL=http://searxng:8080
    depends_on:
      - searxng

  searxng:
    image: searxng/searxng:latest
    ports:
      - "8080:8080"
```

## Configuration

### How do I change the LLM model?

1. **Via Web UI**: Settings → LLM Provider → Select model
2. **Via Environment**: Set `LDR_LLM_MODEL` and `LDR_LLM_PROVIDER`
3. **Via API**: Pass model parameters in requests

### Where should I configure settings?

**Important**: The `.env` file method is deprecated. Use the web UI settings instead:
1. Run the web app: `python -m local_deep_research.web.app`
2. Navigate to Settings
3. Configure your preferences
4. Settings are saved to the database

For a complete reference of all settings, defaults, and environment variables, see [CONFIGURATION.md](CONFIGURATION.md).

### How do I download Ollama models in Docker?

**Note**: If you use cookiecutter with Ollama, it will automatically download an initial model that you specify during setup.

To manually download additional models:
```bash
# Connect to the Ollama container
docker exec -it ollama ollama pull llama3:8b

# Or if using docker-compose
docker-compose exec ollama ollama pull llama3:8b
```

### Which Ollama model should I use?

Recommended models:
- **Best quality**: `llama3:70b` (requires 48GB+ VRAM)
- **Balanced**: `gemma3:12b` (good quality/speed trade-off)
- **Fastest**: `llama3:8b`, `mistral:7b`, or `gemma:7b`

For data-driven picks, see the community-maintained **[LDR Benchmarks dataset on Hugging Face](https://huggingface.co/datasets/local-deep-research/ldr-benchmarks)** — accuracy results submitted by other LDR users across local and cloud models, sortable by model, search engine, and strategy. Useful before downloading multi-GB weights.

## Common Errors

### "Error: max_workers must be greater than 0"

This means LDR cannot connect to your LLM. Check:
1. Ollama is running: `ollama list`
2. You have models downloaded: `ollama pull llama3:8b`
3. Correct model name in settings
4. For Docker: Ensure containers can communicate

### "No module named 'local_deep_research'"

Reinstall the package:
```bash
pip uninstall local-deep-research
pip install local-deep-research
```

### "404 Error" when viewing results

This issue should be resolved in versions 0.5.2 and later. If you're still experiencing it:
1. Refresh the page
2. Check if research actually completed in logs
3. Update to the latest version

### Research gets stuck or shows empty headings

Common causes:
- "Search snippets only" disabled (must be enabled for SearXNG)
- Rate limiting from search engines
- LLM connection issues

Solutions:
1. Reset settings to defaults
2. Use fewer iterations (2-3)
3. Limit questions per iteration (3-4)

### "'str' object has no attribute 'items'"

This issue should be fixed in recent versions. If you encounter it, ensure you're using the correct environment variable format. Remove deprecated variables:
- `LDR_SEARCH_ENGINE_WEB`
- `LDR_SEARCH_ENGINE_AUTO`
- `LDR_SEARCH_ENGINE_DEFAULT`

Use `LDR_SEARCH_TOOL` instead if needed.

### Chinese / Japanese / Korean text is missing from exported PDFs

PDF export uses WeasyPrint, which resolves glyphs through the host's installed fonts. If your system has no CJK font installed, those characters disappear silently from the PDF even though they render fine in the browser. Install a CJK font package:

- **Debian/Ubuntu:** `sudo apt install fonts-noto-cjk && fc-cache -fv`
- **Fedora/RHEL:** `sudo dnf install google-noto-sans-cjk-fonts && fc-cache -fv`
- **Alpine:** `apk add font-noto-cjk`
- **macOS / Windows:** CJK fonts ship with the OS — no install needed.
- **Docker (official image):** `fonts-noto-cjk` is bundled, no action needed.

After installing, restart LDR and re-export the PDF.

## Search Engines

### SearXNG connection errors

1. **Verify SearXNG is running**:
   ```bash
   docker ps | grep searxng
   curl http://localhost:8080
   ```

2. **For Docker networking issues**:
   - Use `http://searxng:8080` (container name) not `localhost`
   - Or use `--network host` mode

3. **Check browser access**: Navigate to `http://localhost:8080`

### Rate limit errors

Solutions:
1. Check status: `python -m local_deep_research.web_search_engines.rate_limiting status`
2. Reset limits: `python -m local_deep_research.web_search_engines.rate_limiting reset`
3. Use `auto` search tool for automatic fallbacks
4. Add premium search engines

### "Invalid value" errors from SearXNG

Ensure "Search snippets only" is enabled in settings. This is required for SearXNG.

### Captcha errors

Some search engines detect bot activity. Solutions:
- Use SearXNG instead of direct search engines
- Add delays between searches
- Use premium APIs (Tavily, SerpAPI)

## LLM Configuration

### Cannot connect to Ollama

1. **Verify Ollama installation**:
   ```bash
   ollama --version
   ollama list
   ```

2. **For Docker**: Use correct URL
   - From host: `http://localhost:11434`
   - From container: `http://ollama:11434` or `http://host.docker.internal:11434`

### LM Studio connection issues

LM Studio runs on your host machine, but Docker containers can't reach `localhost` (it refers to the container itself). If you see "Model 1" / "Model 2" instead of actual models, this is why.

**Mac/Windows (Docker Desktop):**
- Use `http://host.docker.internal:1234` instead of `localhost:1234`

**Linux (#1358):**

Option A - Use your host's actual IP address:
1. Find your IP: `hostname -I | awk '{print $1}'` (gives something like `192.168.1.xxx`)
2. Set LM Studio URL to: `http://192.168.1.xxx:1234`
3. Ensure LM Studio is listening on `0.0.0.0` (not just localhost)

Option B - Enable `host.docker.internal` on Linux:
Add to your docker-compose.yml:
```yaml
services:
  local-deep-research:
    extra_hosts:
      - "host.docker.internal:host-gateway"
```
Then use `http://host.docker.internal:1234`

### No models appear after I set my LM Studio API key

If you paste the API key into Settings → LLM → LM Studio and immediately click the model-refresh button, the key may not have been saved yet — the field saves on blur (when you click or tab away from it), not on keypress. Click outside the API key field, or press Tab, to save the value first, then click the refresh button. The model list should populate normally.

### LM Studio API key — what value should I use?

LM Studio does not validate API keys by default. You can leave the API key field **blank**, or set it to any non-empty string (e.g. `lm-studio` or `not-needed`). Either will work.

### Should I use the LM Studio provider or the generic OpenAI-compatible provider?

Use the dedicated **LM Studio** provider (Settings → LLM → Provider → LM Studio) rather than the generic *OpenAI-compatible* option. The dedicated provider is pre-configured with the correct defaults for LM Studio and avoids common compatibility issues.

### Context length not respected

Known issue with Ollama (#500). Workaround:
- Set context length when pulling model: `ollama pull llama3:8b --context-length 8192`

### Model not in dropdown list

Current limitation (#179). Workarounds:
1. Type the exact model name in the dropdown field
2. Edit database directly
3. Use environment variables

### How do I use OpenRouter?

[OpenRouter](https://openrouter.ai/) provides access to 100+ models through a single API. It uses an OpenAI-compatible API format.

**Quick Setup:**

1. **Get API Key**: Sign up at [openrouter.ai](https://openrouter.ai/) and generate an API key

2. **Configure via Web UI** (Recommended):
   - Navigate to Settings → LLM Provider
   - Select "OpenAI-Compatible Endpoint" (not "OpenRouter" - use the generic OpenAI endpoint option)
   - Set Endpoint URL: `https://openrouter.ai/api/v1`
   - Enter your OpenRouter API key
   - Select a model from the dropdown (it will auto-populate with OpenRouter models)

3. **Configure via Environment Variables** (for Docker/CI/CD):
   ```bash
   export LDR_LLM_PROVIDER=openai_endpoint
   export LDR_LLM_OPENAI_ENDPOINT_URL=https://openrouter.ai/api/v1
   export LDR_LLM_OPENAI_ENDPOINT_API_KEY="<your-api-key>"
   export LDR_LLM_MODEL=anthropic/claude-3.5-sonnet
   ```

4. **Docker Compose Example**:
   ```yaml
   services:
     local-deep-research:
       environment:
         - LDR_LLM_PROVIDER=openai_endpoint
         - LDR_LLM_OPENAI_ENDPOINT_URL=https://openrouter.ai/api/v1
         - LDR_LLM_OPENAI_ENDPOINT_API_KEY=<your-api-key>
         - LDR_LLM_MODEL=anthropic/claude-3.5-sonnet
   ```

**Available Models**: Browse at [openrouter.ai/models](https://openrouter.ai/models)

**Common Issues**:
- **"Model not found"**: Ensure the model name exactly matches OpenRouter's format (e.g., `anthropic/claude-3.5-sonnet`)
- **Authentication errors**: Verify your API key is correct and has credits
- **Can't find OpenRouter in provider list**: Select "OpenAI-Compatible Endpoint" instead

See also: [Environment Variables Documentation](env_configuration.md#openrouter) | [Full Configuration Reference](CONFIGURATION.md)

## Local Document Search

### How do I search my local documents?

Use the **Collections** system in the Web UI:

1. **Navigate** to the Collections page in the sidebar
2. **Create a collection** (e.g., "Research Papers", "Project Docs")
3. **Upload documents** directly through the UI — supported formats include PDF, TXT, MD, DOCX, and many more
4. **Search** your collections by selecting them as a search engine, or use **"Search All Collections"** (Library RAG) to search across everything

### Local search not finding documents

Common issues:
1. **First search is slow** — initial indexing takes time
2. **File types** — ensure supported formats (PDF, TXT, MD, DOCX)
3. **Collection not indexed** — re-upload or re-index via the Collections UI

## Performance & Optimization

### Research is too slow

1. **Reduce complexity**:
   - In the Web UI: Use Settings to reduce iterations and questions per iteration
   - Via API:
   ```python
   quick_summary(
       query="your query",
       iterations=1,  # Start with 1
       questions_per_iteration=2  # Limit sub-questions
   )
   ```

2. **Use faster models**:
   - Local: `mistral:7b`
   - Cloud: `gpt-3.5-turbo`

3. **Enable "Search snippets only"** (required for SearXNG)

### High memory usage

- Use smaller models (7B instead of 70B)
- Limit document collection size
- Use quantized models (GGUF format)

## Docker Issues

### Containers can't communicate

1. **Use Docker Compose** (recommended)
2. **Or use host networking**:
   ```bash
   docker run --network host ...
   ```
3. **Check container names** in URLs

### Port 5000 not accessible on Windows

This usually means you copied a `docker run … --network host …` recipe from the Linux quick-start. `--network host` is a Linux-only feature: on Docker Desktop (Mac, Windows, WSL2) it silently drops the `-p 5000:5000` publish, so the WebUI looks unreachable. As a side effect, `localhost` inside the container also stops resolving to your host's Ollama / SearXNG ports, so once you remove `--network host` the container can no longer reach them on `localhost`.

**Easiest fix:** use Docker Compose instead. The bundled `docker-compose.yml` wires SearXNG and Ollama via service names (`http://searxng:8080`, `http://ollama:11434`) so nothing on the host needs `localhost`/`host.docker.internal` swapping:

```bash
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml
docker compose up -d
```

**If you want to stay on `docker run`:** drop `--network host`, keep `-p 5000:5000`, and point Ollama/SearXNG at `host.docker.internal` instead of `localhost`. Either set the URLs in **Settings → LLM** and **Settings → Search → SearXNG** after first login, or pass them as env vars on launch:

```bash
docker run -d -p 5000:5000 \
  --name local-deep-research \
  --add-host=host.docker.internal:host-gateway \
  --volume 'deep-research:/data' \
  -e LDR_DATA_DIR=/data \
  -e LDR_LLM_OLLAMA_URL=http://host.docker.internal:11434 \
  -e LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://host.docker.internal:8080 \
  localdeepresearch/local-deep-research
```

Note: env vars passed on `docker run` always win over values you later change in the Settings UI (the env-var override is checked on every read), so if you plan to manage URLs from the UI, leave the `-e LDR_...` lines off.

### "Database is locked" errors

Stop all containers and restart:
```bash
docker-compose down
docker-compose up -d
```

## Unraid Deployment

### How do I install LDR on Unraid?

See the [complete Unraid deployment guide](deployment/unraid.md) for detailed instructions on:
- Template repository installation (recommended)
- Docker Compose Manager setup
- GPU acceleration
- Volume configuration

### Common Unraid Issues

**Settings don't persist?** Check that `/data` is mapped to `/mnt/user/appdata/local-deep-research/data`

**Port 5000 in use?** Change host port mapping to `5050:5000` (don't change container port)

**GPU not detected?** Install Nvidia-Driver plugin and configure Docker runtime - see [GPU setup guide](deployment/unraid.md#-gpu-acceleration-nvidia)

**"Update Ready" always showing?** Normal for Docker Compose Manager - update via Compose section, not Docker tab

For complete troubleshooting, see the [Unraid deployment guide](deployment/unraid.md#-troubleshooting)

### Can't access LDR WebUI from other devices

Check network configuration:
1. Verify container is running in **Docker** tab
2. Ensure port mapping is correct (`5000:5000`)
3. Test locally first: `http://[unraid-ip]:5000`
4. Check Unraid firewall if enabled
5. For multi-container setup, ensure all on same network (`ldr-network`)

### Docker in Proxmox LXC: Permission Errors

If you see either of these errors in container logs:
```
chown: changing ownership of '/data/logs': Operation not permitted
```
or:
```
error: failed switching to "ldruser": operation not permitted
```

This means Linux capabilities needed by the entrypoint are blocked by the LXC container. The `chown` error indicates missing `CAP_CHOWN`/`CAP_FOWNER`, while the `setpriv` error indicates missing `CAP_SETUID`/`CAP_SETGID`.

**Solutions (try in order):**

1. **Ensure nesting is enabled** in your Proxmox LXC container:
   - Proxmox UI → Container → Options → Features → check "Nesting"
   - Or in config: `features: nesting=1,keyctl=1`

2. **If nesting is already enabled**, your LXC may have a restrictive AppArmor profile. Try:
   ```bash
   # In /etc/pve/lxc/<CTID>.conf
   lxc.apparmor.profile: unconfined
   ```
   Then restart the LXC container.

3. **Use a privileged LXC container** (trades security for compatibility):
   - When creating the LXC with Proxmox community scripts, select "Privileged" in advanced settings

**Background:** The LDR container runs its entrypoint as root to fix volume permissions, then uses `setpriv` to drop to a non-root user (`ldruser`) for security. `setpriv` calls `setuid()`/`setgid()` which require these capabilities. In standard Docker this works out of the box, but Docker-inside-LXC inherits the outer container's capability restrictions.

## Platform-Specific Issues

### Windows filename errors (#339)

LDR may generate invalid filenames. Fixed in recent versions, update to latest.

### macOS: Port 5000 in use (AirPlay conflict)

macOS Monterey (12.0+) uses port 5000 for AirPlay Receiver, which conflicts with LDR's default port. See [Port Conflict Troubleshooting](troubleshooting.md#port-conflicts) for solutions.

### macOS M1/M2/M3 issues

- Build your own Docker image for ARM
- Use native Ollama installation
- Some models may not be optimized for Apple Silicon

### WSL2 networking problems

Common on Windows. Solutions:
1. Use `127.0.0.1` instead of `0.0.0.0`
2. Check WSL2 firewall settings
3. Restart WSL: `wsl --shutdown`

## Getting Help

- **Discord**: [Join our community](https://discord.gg/ttcqQeFcJ3)
- **GitHub Issues**: [Report bugs](https://github.com/LearningCircuit/local-deep-research/issues)
- **Reddit**: [r/LocalDeepResearch](https://www.reddit.com/r/LocalDeepResearch/)

When reporting issues, include:
- Error messages and logs
- Your configuration (OS, Docker/pip, models)
- Steps to reproduce
- What you've already tried

## Related Documentation

- [Installation Guide](https://github.com/LearningCircuit/local-deep-research/wiki/Installation)
- [Search Engines Guide](search-engines.md)
- [Features Documentation](features.md)
- [API Documentation](api-quickstart.md)
- [Configuration Guide](env_configuration.md)
- [Full Configuration Reference](CONFIGURATION.md)