Common Issues

Installation Problems

Command not found: make, pnpm, uv, or nginx

Problem: Missing required dependencies when running make check or make dev.Solution:macOS:

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install pnpm nginx
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify Node.js version (requires 22+)
node --version
# If Node version is below 22, install the latest:
brew install node@22

Linux (Ubuntu/Debian):

# Install Node.js 22+ via NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm
npm install -g pnpm

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install nginx
sudo apt-get install -y nginx

Windows:

# Use Scoop package manager
scoop install nodejs-lts pnpm nginx

# Install uv
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Python version mismatch or module not found errors

Problem: Errors like ModuleNotFoundError or Python 3.12+ required.Solution:DeerFlow requires Python 3.12 or higher. Install using uv:

# From the backend directory
cd backend

# Let uv handle Python installation and dependencies
uv sync

# Verify Python version
uv run python --version
# Should output: Python 3.12.x or higher

If you still encounter issues:

# Remove existing virtual environment
rm -rf .venv

# Reinstall
uv sync

Docker Desktop not running or Docker daemon not accessible

Problem: Cannot connect to the Docker daemon when using Docker sandbox mode.Solution:

Start Docker Desktop:
- macOS/Windows: Launch Docker Desktop application
- Verify it’s running: Look for Docker icon in system tray

Check Docker daemon:

docker ps
# Should list running containers (or empty list if none running)

Restart Docker service (Linux):

sudo systemctl start docker
sudo systemctl enable docker

Add user to docker group (Linux):

sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Configuration Errors

Config file not found

Problem: Configuration file not found error when starting services.Solution:The configuration file must be in the project root directory, not the backend directory.

Create config from example:

# From project root (deer-flow/)
cd deer-flow
cp config.example.yaml config.yaml

Verify location:

# Should be in project root
ls -la config.yaml
# Output: -rw-r--r--  1 user  staff  10234 Mar 04 10:00 config.yaml

Alternative: Set environment variable:

export DEER_FLOW_CONFIG_PATH="/absolute/path/to/config.yaml"

Configuration file search order:

DEER_FLOW_CONFIG_PATH environment variable
backend/config.yaml (current directory)
deer-flow/config.yaml (parent directory - recommended)

Invalid API key or authentication failed

Problem: Invalid API key or Authentication failed errors when making LLM requests.Solution:

Verify environment variables are set:

echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY
# Should output your API key, not empty

Check config.yaml uses environment variable syntax:

models:
  - name: gpt-4
    api_key: $OPENAI_API_KEY  # Correct: $ prefix
    # NOT: api_key: your-key-here  # Wrong: hardcoded

Set environment variables properly:

# Option A: Add to .env file in project root
echo "OPENAI_API_KEY=sk-..." >> .env

# Option B: Export in shell
export OPENAI_API_KEY="sk-..."

# Option C: Add to shell profile (~/.bashrc, ~/.zshrc)
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc
source ~/.zshrc

Restart services after setting variables:
```
make stop
make dev
```

Test API key directly:

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'

Extensions config not found or MCP servers failing to load

Problem: extensions_config.json not found or MCP servers not working.Solution:

Create extensions config from example:

# From project root
cp extensions_config.example.json extensions_config.json

Verify MCP server configuration:

{
  "mcpServers": {
    "filesystem": {
      "enabled": true,  // Must be true
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

Check environment variables in MCP config:

{
  "mcpServers": {
    "github": {
      "enabled": true,
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"  // Must start with $
      }
    }
  }
}

Validate JSON syntax:

# Use jq to validate JSON
jq . extensions_config.json
# Should output formatted JSON, not errors

Restart to reload config:
```
make stop
make dev
```

Model not found or unsupported provider

Problem: Model 'xxx' not found or Failed to import provider.Solution:

Install required provider package: DeerFlow supports any LangChain-compatible provider. Install the appropriate package:

# From backend directory
cd backend

# OpenAI
uv add langchain-openai

# Anthropic
uv add langchain-anthropic

# Google (Gemini)
uv add langchain-google-genai

# DeepSeek
uv add langchain-deepseek

# Other providers
uv add langchain-<provider-name>

Verify model configuration in config.yaml:

models:
  - name: gpt-4
    display_name: GPT-4
    use: langchain_openai:ChatOpenAI  # Must match installed package
    model: gpt-4  # Must be valid model ID for the provider

Check for typos in provider path:
- Correct: langchain_openai:ChatOpenAI (underscore, not hyphen)
- Correct: langchain_anthropic:ChatAnthropic
- Wrong: langchain-openai:ChatOpenAI

Test model directly:

cd backend
uv run python -c "from langchain_openai import ChatOpenAI; print('OK')"

Dependency Issues

Port already in use (2024, 8001, 3000, 2026)

Problem: Address already in use when starting services.Solution:DeerFlow uses multiple ports:

2024: LangGraph Server
8001: Gateway API
3000: Frontend
2026: Nginx (unified entry point)
8002: Provisioner (optional, only in Kubernetes mode)
8080+: Sandbox containers (dynamic)

Find process using the port:

# macOS/Linux
lsof -i :2026
lsof -i :2024

# Windows
netstat -ano | findstr :2026

Kill the conflicting process:

# macOS/Linux
kill -9 <PID>

# Windows
taskkill /PID <PID> /F

Stop DeerFlow services properly:
```
make stop
```
Change port (advanced): Edit service configurations if you need different ports:
- LangGraph: backend/langgraph.json
- Gateway: backend/src/gateway/app.py
- Frontend: frontend/package.json (dev script)
- Nginx: nginx.conf

npm or pnpm install failures

Problem: Frontend dependencies fail to install with errors like EACCES or ERESOLVE.Solution:

Use pnpm instead of npm:

# Install pnpm if not already installed
npm install -g pnpm

# From project root
make install

Clear cache and reinstall:

# From frontend directory
cd frontend
rm -rf node_modules pnpm-lock.yaml
pnpm install

Fix permissions (macOS/Linux):

sudo chown -R $USER:$USER ~/.pnpm-store
sudo chown -R $USER:$USER node_modules

Use Node.js 22+:

node --version
# Should be v22.x.x or higher

# If not, upgrade:
brew install node@22  # macOS
# or use nvm:
nvm install 22
nvm use 22

General Troubleshooting

Services start but frontend shows connection error

Problem: Frontend loads but cannot connect to backend services.Solution:

Verify all services are running:

# Check processes
ps aux | grep langgraph
ps aux | grep uvicorn  # Gateway
ps aux | grep next     # Frontend
ps aux | grep nginx

Test backend endpoints directly:

# LangGraph health (through nginx)
curl http://localhost:2026/api/langgraph/info

# Gateway health (through nginx)
curl http://localhost:2026/api/models

# Direct ports (if nginx not working)
curl http://localhost:2024/info      # LangGraph
curl http://localhost:8001/health    # Gateway

Check nginx configuration:

# Test nginx config
nginx -t

# View nginx error logs
tail -f /usr/local/var/log/nginx/error.log  # macOS
tail -f /var/log/nginx/error.log            # Linux

Restart services in order:
```
make stop
# Wait 5 seconds
make dev
```

Check frontend environment variables:

# From frontend directory
cat .env.local
# Should have:
# NEXT_PUBLIC_LANGGRAPH_BASE_URL=/api/langgraph
# NEXT_PUBLIC_BACKEND_BASE_URL=(empty or not set)

Clean reinstall procedure

Problem: Multiple issues or corrupted state requiring fresh start.Solution:Perform a complete clean reinstall:

# 1. Stop all services
make stop

# 2. Remove all generated files and dependencies
cd backend
rm -rf .venv .deer-flow

cd ../frontend
rm -rf node_modules .next pnpm-lock.yaml

cd ..

# 3. Clean Docker resources (if using Docker sandbox)
docker system prune -a --volumes -f

# 4. Reinstall dependencies
make install

# 5. Verify configuration files exist
ls -la config.yaml extensions_config.json .env

# 6. Start services
make dev

# 7. Verify services are running
curl http://localhost:2026/api/models

Next Steps

Sandbox Errors - Docker and container issues
Model Configuration - LLM provider problems
Performance Optimization - Speed and resource issues
Configuration Guide - Complete configuration reference

Architecture

Development

Troubleshooting

Installation Problems

Configuration Errors

Dependency Issues

General Troubleshooting

Next Steps

Build docs developers (and LLMs) love

Architecture

Development

Troubleshooting

​Installation Problems

​Configuration Errors

​Dependency Issues

​General Troubleshooting

​Next Steps

Build docs developers (and LLMs) love

Installation Problems

Configuration Errors

Dependency Issues

General Troubleshooting

Next Steps