deerflow-factory/deer-flow/.agent/skills/smoke-test/references/troubleshooting.md

Troubleshooting Guide

This document lists common issues encountered during DeerFlow smoke testing and how to resolve them.

Code Update Issues

Issue: git pull Fails with a Merge Conflict Warning

Symptoms:

error: Your local changes to the following files would be overwritten by merge

Solutions:

1. Option A: Commit local changes first

   git add .
   git commit -m "Save local changes"
   git pull origin main
   

2. Option B: Stash local changes

   git stash
   git pull origin main
   git stash pop  # Restore changes later if needed
   

3. Option C: Discard local changes (use with caution)

   git reset --hard HEAD
   git pull origin main
   

---

Local Mode Environment Issues

Issue: Node.js Version Is Too Old

Symptoms:

Node.js version is too old. Requires 22+, got x.x.x

Solutions:

1. Install or upgrade Node.js with nvm:

   nvm install 22
   nvm use 22
   

2. Or download and install it from the official website: https://nodejs.org/

3. Verify the version:

   node --version
   

---

Issue: pnpm Is Not Installed

Symptoms:

command not found: pnpm

Solutions:

1. Install pnpm with npm:

   npm install -g pnpm
   

2. Or use the official installation script:

   curl -fsSL https://get.pnpm.io/install.sh | sh -
   

3. Verify the installation:

   pnpm --version
   

---

Issue: uv Is Not Installed

Symptoms:

command not found: uv

Solutions:

1. Use the official installation script:

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

2. macOS users can also install it with Homebrew:

   brew install uv
   

3. Verify the installation:

   uv --version
   

---

Issue: nginx Is Not Installed

Symptoms:

command not found: nginx

Solutions:

1. macOS (Homebrew):

   brew install nginx
   

2. Ubuntu/Debian:

   sudo apt update
   sudo apt install nginx
   

3. CentOS/RHEL:

   sudo yum install nginx
   

4. Verify the installation:

   nginx -v
   

---

Issue: Port Is Already in Use

Symptoms:

Error: listen EADDRINUSE: address already in use :::2026

Solutions:

1. Find the process using the port:

   lsof -i :2026  # macOS/Linux
   netstat -ano | findstr :2026  # Windows
   

2. Stop that process:

   kill -9 <PID>  # macOS/Linux
   taskkill /PID <PID> /F  # Windows
   

3. Or stop DeerFlow services first:

   make stop
   

---

Local Mode Dependency Installation Issues

Issue: make install Fails Due to Network Timeout

Symptoms: Network timeouts or connection failures occur during dependency installation.

Solutions:

1. Configure pnpm to use a mirror registry:

   pnpm config set registry https://registry.npmmirror.com
   

2. Configure uv to use a mirror registry:

   uv pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
   

3. Retry the installation:

   make install
   

---

Issue: Python Dependency Installation Fails

Symptoms: Errors occur during uv sync.

Solutions:

1. Clean the uv cache:

   cd backend
   uv cache clean
   

2. Resync dependencies:

   cd backend
   uv sync
   

3. View detailed error logs:

   cd backend
   uv sync --verbose
   

---

Issue: Frontend Dependency Installation Fails

Symptoms: Errors occur during pnpm install.

Solutions:

1. Clean the pnpm cache:

   cd frontend
   pnpm store prune
   

2. Remove node_modules and the lock file:

   cd frontend
   rm -rf node_modules pnpm-lock.yaml
   

3. Reinstall:

   cd frontend
   pnpm install
   

---

Local Mode Service Startup Issues

Issue: Services Exit Immediately After Startup

Symptoms: Processes exit quickly after running make dev-daemon.

Solutions:

1. Check log files:

   tail -f logs/langgraph.log
   tail -f logs/gateway.log
   tail -f logs/frontend.log
   tail -f logs/nginx.log
   

2. Check whether config.yaml is configured correctly

3. Check environment variables in the .env file

4. Confirm that required ports are not occupied

5. Stop all services and restart:

   make stop
   make dev-daemon
   

---

Issue: Nginx Fails to Start Because Temp Directories Do Not Exist

Symptoms:

nginx: [emerg] mkdir() "/opt/homebrew/var/run/nginx/client_body_temp" failed (2: No such file or directory)

Solutions: Add local temp directory configuration to docker/nginx/nginx.local.conf so nginx uses the repository's temp directory.

Add the following at the beginning of the http block:

client_body_temp_path temp/client_body_temp;
proxy_temp_path temp/proxy_temp;
fastcgi_temp_path temp/fastcgi_temp;
uwsgi_temp_path temp/uwsgi_temp;
scgi_temp_path temp/scgi_temp;

Note: The temp/ directory under the repository root is created automatically by make dev or make dev-daemon.

---

Issue: Nginx Fails to Start (General)

Symptoms: The nginx process fails to start or reports an error.

Solutions:

1. Check the nginx configuration:

   nginx -t -c docker/nginx/nginx.local.conf -p .
   

2. Check nginx logs:

   tail -f logs/nginx.log
   

3. Ensure no other nginx process is running:

   ps aux | grep nginx
   

4. If needed, stop existing nginx processes:

   pkill -9 nginx
   

---

Issue: Frontend Compilation Fails

Symptoms: Compilation errors appear in frontend.log.

Solutions:

1. Check frontend logs:

   tail -f logs/frontend.log
   

2. Check whether Node.js version is 22+

3. Reinstall frontend dependencies:

   cd frontend
   rm -rf node_modules .next
   pnpm install
   

4. Restart services:

   make stop
   make dev-daemon
   

---

Issue: Gateway Fails to Start

Symptoms: Errors appear in gateway.log.

Solutions:

1. Check gateway logs:

   tail -f logs/gateway.log
   

2. Check whether config.yaml exists and has valid formatting

3. Check whether Python dependencies are complete:

   cd backend
   uv sync
   

4. Confirm that the LangGraph service is running normally (if not in gateway mode)

---

Issue: LangGraph Fails to Start

Symptoms: Errors appear in langgraph.log.

Solutions:

1. Check LangGraph logs:

   tail -f logs/langgraph.log
   

2. Check config.yaml

3. Check whether Python dependencies are complete

4. Confirm that port 2024 is not occupied

---

Docker-Related Issues

Issue: Docker Commands Cannot Run

Symptoms:

Cannot connect to the Docker daemon

Solutions:

1. Confirm that Docker Desktop is running
2. macOS: check whether the Docker icon appears in the top menu bar
3. Linux: run sudo systemctl start docker
4. Run docker info again to verify

---

Issue: make docker-init Fails to Pull the Image

Symptoms:

Error pulling image: connection refused

Solutions:

1. Check network connectivity
2. Configure a Docker image mirror if needed
3. Check whether a proxy is required
4. Switch to local installation mode if necessary (recommended)

---

Configuration File Issues

Issue: config.yaml Is Missing or Invalid

Symptoms:

Error: could not read config.yaml

Solutions:

1. Regenerate the configuration file:

   make config
   

2. Check YAML syntax:

   • Make sure indentation is correct (use 2 spaces)
   • Make sure there are no tab characters
   • Check that there is a space after each colon

3. Use a YAML validation tool to check the format

---

Issue: Model API Key Is Not Configured

Symptoms: After services start, API requests fail with authentication errors.

Solutions:

1. Edit the .env file and add the API key:

   OPENAI_API_KEY=your-actual-api-key-here
   

2. Restart services (local mode):

   make stop
   make dev-daemon
   

3. Restart services (Docker mode):

   make docker-stop
   make docker-start
   

4. Confirm that the model configuration in config.yaml references the environment variable correctly

---

Service Health Check Issues

Issue: Frontend Page Is Not Accessible

Symptoms: The browser shows a connection failure when visiting http://localhost:2026.

Solutions (local mode):

1. Confirm that the nginx process is running:

   ps aux | grep nginx
   

2. Check nginx logs:

   tail -f logs/nginx.log
   

3. Check firewall settings

Solutions (Docker mode):

1. Confirm that the nginx container is running:

   docker ps | grep nginx
   

2. Check nginx logs:

   cd docker && docker compose -p deer-flow-dev -f docker-compose-dev.yaml logs nginx
   

3. Check firewall settings

---

Issue: API Gateway Health Check Fails

Symptoms: Accessing /health returns an error or times out.

Solutions (local mode):

1. Check gateway logs:

   tail -f logs/gateway.log
   

2. Confirm that config.yaml exists and has valid formatting

3. Check whether Python dependencies are complete

4. Confirm that the LangGraph service is running normally

Solutions (Docker mode):

1. Check gateway container logs:

   make docker-logs-gateway
   

2. Confirm that config.yaml is mounted correctly

3. Check whether Python dependencies are complete

4. Confirm that the LangGraph service is running normally

---

Common Diagnostic Commands

Local Mode Diagnostics

View All Service Processes

ps aux | grep -E "(langgraph|uvicorn|next|nginx)" | grep -v grep

View Service Logs

# View all logs
tail -f logs/*.log

# View specific service logs
tail -f logs/langgraph.log
tail -f logs/gateway.log
tail -f logs/frontend.log
tail -f logs/nginx.log

Stop All Services

make stop

Fully Reset the Local Environment

make stop
make clean
make config
make install
make dev-daemon

---

Docker Mode Diagnostics

View All Container Status

docker ps -a

View Container Resource Usage

docker stats

Enter a Container for Debugging

docker exec -it deer-flow-gateway sh

Clean Up All DeerFlow-Related Containers and Images

make docker-stop
cd docker && docker compose -p deer-flow-dev -f docker-compose-dev.yaml down -v

Fully Reset the Docker Environment

make docker-stop
make clean
make config
make docker-init
make docker-start

---

Get More Help

If the solutions above do not resolve the issue:

1. Check the GitHub issues for the project: https://github.com/bytedance/deer-flow/issues
2. Review the project documentation: README.md and the backend/docs/ directory
3. Open a new issue and include detailed error logs