Sandbox Errors

Docker Container Issues

Container runtime not detected or Docker not available

Problem: Docker not available or Container runtime not detected errors.Solution:DeerFlow supports multiple container runtimes:

macOS: Automatically prefers Apple Container if available, falls back to Docker
Other platforms: Uses Docker

Verify Docker is running:

docker ps
# Should list containers (empty list is OK)

On macOS with Apple Container:

# Check if Apple Container is installed
container --version

# Start Apple Container service
container system start

# If not installed, download from:
# https://github.com/apple/container/releases

Force Docker runtime (if Apple Container has issues):

# Temporarily rename container command to force Docker fallback
sudo mv /opt/homebrew/bin/container /opt/homebrew/bin/container.bak

# Restart DeerFlow
make stop && make dev

# Restore when ready
sudo mv /opt/homebrew/bin/container.bak /opt/homebrew/bin/container

Check Docker Desktop is running:
- macOS/Windows: Launch Docker Desktop app
- Linux: sudo systemctl start docker

Sandbox image pull failing or timing out

Problem: Failed to pull image or long wait times when first using sandbox.Solution:The sandbox image is large (~500MB+) and pulled on first use.

Pre-pull the image (recommended):
```
# From project root
make setup-sandbox
```

Manual pull with progress:

# For Docker
docker pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

# For Apple Container (macOS)
container pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

Use alternative registry (if blocked):

# In config.yaml
sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  image: docker.io/your-registry/all-in-one-sandbox:latest

Verify image exists after pull:

# Docker
docker images | grep all-in-one-sandbox

# Apple Container
container images

Check disk space:

df -h
# Need at least 2GB free for image + containers

Container fails to start or exits immediately

Problem: Sandbox container starts but exits with error, or never becomes ready.Solution:

Check container logs:

# List containers (including stopped)
docker ps -a | grep deer-flow-sandbox

# View logs for specific container
docker logs <container-id>

# For Apple Container
container list
container logs <container-id>

Verify port availability:

# Check if port 8080 (or configured port) is available
lsof -i :8080

# If in use, either:
# a) Kill the process using it
kill -9 <PID>

# b) Change sandbox port in config.yaml
# sandbox:
#   port: 8090  # Use different port

Check container resource limits:

# Verify Docker has enough resources
docker info | grep -i memory
docker info | grep -i cpu

# Increase in Docker Desktop:
# Settings → Resources → Increase Memory to 4GB+

Test container manually:

# Try running container directly
docker run --rm -p 8080:8080 \
  enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

# Should see sandbox startup logs
# If fails, check error message

Verify image architecture matches system:

# Check your system architecture
uname -m
# arm64 (Apple Silicon) or x86_64 (Intel)

# Verify image supports your architecture
docker inspect enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest \
  | grep -i architecture

Multiple sandbox containers running or orphaned containers

Problem: Many sandbox containers accumulate over time, consuming resources.Solution:

Clean up DeerFlow sandbox containers:

# From project root
make stop
# This automatically cleans up sandbox containers

Manual cleanup script:

# Clean all DeerFlow sandbox containers
./scripts/cleanup-containers.sh deer-flow-sandbox

Remove all stopped containers:

# Docker
docker container prune -f

# Apple Container
container prune

Force remove specific container:

# Docker
docker rm -f <container-id>

# Apple Container
container rm -f <container-id>

Verify cleanup:

# Should show no DeerFlow containers
docker ps -a | grep deer-flow-sandbox

Configure auto-removal (already default):

# In config.yaml - already set by default
sandbox:
  use: src.community.aio_sandbox:AioSandboxProvider
  # Containers automatically removed on stop due to --rm flag

Path Mapping Problems

File not found in sandbox despite existing on host

Problem: Agent reports File not found but file exists on host machine.Solution:DeerFlow uses virtual path mapping between host and sandbox:Path Translation:

Agent sees: /mnt/user-data/workspace/file.txt
Host location: backend/.deer-flow/threads/{thread_id}/user-data/workspace/file.txt
Agent sees: /mnt/skills/public/research/SKILL.md
Host location: skills/public/research/SKILL.md

Verify file exists on host:

# From project root
ls -la backend/.deer-flow/threads/<thread-id>/user-data/workspace/

Check path mapping in config:

# In config.yaml
skills:
  path: ../skills  # Host path (relative to backend/)
  container_path: /mnt/skills  # Sandbox path

Verify Docker mounts (if using Docker sandbox):

# Inspect running sandbox container
docker inspect <container-id> | grep -A 10 Mounts

# Should show mounts like:
# /path/to/backend/.deer-flow/threads/xxx → /mnt/user-data
# /path/to/skills → /mnt/skills

Test file access from within container:

# Execute command inside running sandbox
docker exec <container-id> ls -la /mnt/user-data/workspace/

# For Apple Container
container exec <container-id> ls -la /mnt/user-data/workspace/

Common path mistakes:
- ❌ Wrong: read_file("/home/user/file.txt") (not mounted)
- ✅ Correct: read_file("/mnt/user-data/workspace/file.txt")
- ❌ Wrong: Relative paths like ./file.txt (ambiguous)
- ✅ Correct: Absolute paths starting with /mnt/

Skills not found or not loading in sandbox

Problem: Agent reports skills unavailable or cannot access skill files.Solution:

Verify skills directory exists:

# From project root
ls -la skills/public/
ls -la skills/custom/

# Should contain skill directories with SKILL.md files

Check skills configuration:

# In config.yaml
skills:
  path: ../skills  # Must exist relative to backend/
  container_path: /mnt/skills

Verify skills are enabled:

// In extensions_config.json
{
  "skills": {
    "research": {"enabled": true},
    "report-generation": {"enabled": true}
  }
}

Check skill file format:

# Each skill needs SKILL.md with frontmatter
cat skills/public/research/SKILL.md

# Should start with:
# ---
# name: research
# description: ...
# ---

Verify mount in container:

# Check if skills are accessible in sandbox
docker exec <container-id> ls -la /mnt/skills/public/

# Should list skill directories

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

Permission denied errors in sandbox

Problem: Permission denied when accessing files or executing commands in sandbox.Solution:

Check host file permissions:

# Files should be readable by your user
ls -la backend/.deer-flow/threads/
ls -la skills/

# Fix permissions if needed
chmod -R u+rw backend/.deer-flow/
chmod -R u+r skills/

For Docker on Linux - user ID mapping:

# Check your user ID
id -u
# Should match container user (usually 1000)

# If different, fix ownership:
sudo chown -R $USER:$USER backend/.deer-flow/
sudo chown -R $USER:$USER skills/

SELinux issues (Linux):

# If using SELinux, add :z flag to mounts
# Edit docker-compose or mount configuration
# volumes:
#   - ./skills:/mnt/skills:z

Read-only mount issues:

# Verify mounts are not read-only (except skills)
docker inspect <container-id> | grep -i readonly

# Skills should be read-only: true
# user-data should be read-only: false

Windows path permissions:
- Ensure Docker Desktop has access to drive
- Settings → Resources → File Sharing → Add drive

Kubernetes/Provisioner Issues

Provisioner cannot connect to Kubernetes API

Problem: Connection refused to K8s API when using provisioner mode.Solution:

Check Kubernetes cluster is running:

kubectl cluster-info
# Should show cluster endpoint

kubectl get nodes
# Should list at least one node

Enable Kubernetes in Docker Desktop:
- Open Docker Desktop → Settings
- Navigate to Kubernetes tab
- Check “Enable Kubernetes”
- Click “Apply & Restart”
- Wait for Kubernetes to start (may take 2-5 minutes)

Check API server address in kubeconfig:

kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}'
# If shows localhost or 127.0.0.1, provisioner can't reach it

Override API server for provisioner:

# In docker-compose-dev.yaml or docker/docker-compose-dev.yaml
provisioner:
  environment:
    - K8S_API_SERVER=https://host.docker.internal:6443
    # Replace 6443 with your API server port

Verify kubeconfig mount:

# Check provisioner can access kubeconfig
docker exec deer-flow-provisioner ls -la /root/.kube/config

# Should be a file, not a directory
# -rw-r--r-- 1 root root ... config

Test connection from provisioner:

docker exec deer-flow-provisioner kubectl get nodes
# Should list nodes if connection works

Sandbox Pods stuck in Pending or ContainerCreating

Problem: Kubernetes Pods for sandboxes never become Ready.Solution:

Check Pod status and events:

kubectl get pods -n deer-flow
kubectl describe pod <sandbox-pod-name> -n deer-flow
# Look at Events section for errors

Common causes: Image pull issues:

# Pre-pull image on Kubernetes node
docker pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest

Resource constraints:

# Check node resources
kubectl describe node
# Look for CPU/Memory pressure

# Reduce resource requests if needed (in provisioner config)

Volume mount issues:

# Verify host paths exist
ls -la $SKILLS_HOST_PATH
ls -la $THREADS_HOST_PATH

# Paths must be absolute, not relative

Check provisioner logs:

docker logs deer-flow-provisioner
# Look for Pod creation errors

Verify namespace exists:

kubectl get namespace deer-flow
# Should show Active

# Create if missing:
kubectl create namespace deer-flow

Test Pod creation manually:

# Create test Pod to verify K8s setup
kubectl run test-pod -n deer-flow --image=nginx --restart=Never
kubectl get pod test-pod -n deer-flow
# Should become Running

# Clean up
kubectl delete pod test-pod -n deer-flow

Cannot access sandbox URL from backend containers

Problem: Backend can’t reach sandbox via NodePort URL.Solution:

Verify Service was created:

kubectl get svc -n deer-flow
# Should show Service with NodePort type

kubectl describe svc <sandbox-service-name> -n deer-flow
# Note the NodePort value (e.g., 32123)

Test from host machine first:

# Get NodePort from Service
NODE_PORT=$(kubectl get svc -n deer-flow -l sandbox-id=<sandbox-id> \
  -o jsonpath='{.items[0].spec.ports[0].nodePort}')

# Test from host
curl http://localhost:$NODE_PORT/v1/sandbox
# Should return sandbox info

Test from backend container:

# If host test works but container test fails:
docker exec deer-flow-gateway curl http://host.docker.internal:$NODE_PORT/v1/sandbox

Check extra_hosts in docker-compose (Linux):

# In docker-compose-dev.yaml
services:
  gateway:
    extra_hosts:
      - "host.docker.internal:host-gateway"
  langgraph:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Verify NODE_HOST configuration:

# Check provisioner config
docker exec deer-flow-provisioner env | grep NODE_HOST
# Should show: NODE_HOST=host.docker.internal

Check Pod network is reachable:

# Get Pod IP
kubectl get pod -n deer-flow -o wide

# Try direct Pod IP (may not work if network not bridged)
curl http://<pod-ip>:8080/v1/sandbox

Next Steps

Model Configuration - Fix LLM provider issues
Performance Tuning - Optimize sandbox performance
Configuration Guide - Complete sandbox configuration
Provisioner Setup - Detailed Kubernetes setup guide

Architecture

Development

Troubleshooting

Docker Container Issues

Path Mapping Problems

Kubernetes/Provisioner Issues

Next Steps

Architecture

Development

Troubleshooting

​Docker Container Issues

​Path Mapping Problems

​Kubernetes/Provisioner Issues

​Next Steps

Docker Container Issues

Path Mapping Problems

Kubernetes/Provisioner Issues

Next Steps