Skip to content

operations-and-troubleshooting.mdx

Latest commit

 

History

History
189 lines (127 loc) · 6.14 KB

operations-and-troubleshooting.mdx

File metadata and controls

189 lines (127 loc) · 6.14 KB
Raw
title Operations and Troubleshooting
description This page covers day-to-day operational tasks and solutions to common problems when running DeerFlow App.

import { Callout } from "nextra/components";

Operations and Troubleshooting

This page covers day-to-day operational tasks and solutions to common problems when running DeerFlow App.

Log files

All services write logs to the logs/ directory when started with make dev:

File Service
logs/gateway.log FastAPI Gateway API and agent runtime
logs/frontend.log Next.js frontend dev server
logs/nginx.log nginx reverse proxy

Tail logs in real time:

tail -f logs/gateway.log

Adjust the runtime log level in config.yaml:

log_level: debug # debug | info | warning | error

Health checks

Verify each service is responding:

# Gateway health
curl http://localhost:8001/health

# Through nginx (verifies full proxy chain)
curl http://localhost:2026/api/models

Upgrading an existing checkout

Keep your existing config.yaml, .env, and extensions_config.json; do not run make config again. Stop the mode you currently use, pull the update, then start the same mode again:

Current mode Stop Pull and restart
Local development make stop git pull --ff-only && make dev
Local production make stop git pull --ff-only && make start
Docker development make docker-stop git pull --ff-only && make docker-start
Docker production make down git pull --ff-only && make up

Do not run make docker-init after every git pull; it is for first-time sandbox image setup. If the new version needs configuration fields, run make config-upgrade before restarting. It preserves existing values and writes config.yaml.bak before changing the file.

Common problems

The app loads but the agent doesn't respond

  1. Check logs/gateway.log for startup errors.
  2. Verify your model is correctly configured in config.yaml with a valid API key.
  3. Confirm the API key environment variable is set in the shell that ran make dev.
  4. Test the model endpoint directly with curl to rule out network issues.

Model API errors in the agent response

The agent reports an error like "No chat models are configured" or "model not found":

  • Check that the models: section in config.yaml has at least one entry.
  • Verify the name: field matches what you are requesting in the UI.
  • Check that api_key: is referencing the correct environment variable and that the variable is set.

Frontend build fails with BETTER_AUTH_SECRET

Error: BETTER_AUTH_SECRET is required

Set the environment variable before building:

export BETTER_AUTH_SECRET=$(openssl rand -base64 32)
pnpm build

Or set it in your .env file at the repo root.

Sandbox-related tool failures

If file tools (read_file, ls, bash) fail with permission or path errors:

  1. For LocalSandboxProvider: check that allow_host_bash is set correctly and that the agent has read/write access to the thread data directory.
  2. For container sandboxes: verify Docker (or Apple Container) is running and the sandbox image is accessible.
  3. For K8s Provisioner: check that the provisioner service is healthy (curl http://localhost:8002/health) and that the K8s cluster is reachable.

SQLite reports database is locked

This usually means SQLite is handling concurrent writes from multiple users or long-running agent runs. SQLite supports concurrent reads, but only one writer can hold the database lock at a time. In DeerFlow, checkpoint writes and application writes share the same SQLite database file.

For production or multi-user deployments, switch to Postgres:

database:
  backend: postgres
  postgres_url: $DATABASE_URL

run_events:
  backend: db

SQLite should be kept for local development, single-user deployments, or short-lived evaluation environments.

K8s Provisioner not connecting

Connection refused: http://provisioner:8002
  • Ensure the provisioner service is running: docker compose ps.
  • Check that K8S_API_SERVER is set correctly (should point to the K8s API from inside the container, not localhost).
  • Verify ~/.kube/config is mounted and the cluster is reachable from the container host.

MCP tools not loading

If MCP tools appear in extensions_config.json but are not available in the agent:

  1. Check logs/gateway.log for MCP initialization errors.
  2. Verify the MCP server command is installed (npx, uvx, or the relevant binary).
  3. Test the server command manually to confirm it starts without errors.
  4. Set log_level: debug to see detailed MCP loading output.

Memory not persisting across sessions

  • Verify memory.enabled: true in config.yaml.
  • Check that the storage path is writable: ls -la backend/.deer-flow/.
  • Look for memory update errors in logs/gateway.log (search for "memory").

Data backup

Back up the storage backends you use:

  • backend/.deer-flow/threads/ for thread working directories, uploads, and artifacts.
  • backend/.deer-flow/memory.json and backend/.deer-flow/agents/ for learned memory.
  • ${database.sqlite_dir}/deerflow.db when using database.backend: sqlite (default: .deer-flow/data/deerflow.db).
  • Regular database dumps when using database.backend: postgres.
  • The legacy checkpointer.connection_string file if your deployment still configures a standalone checkpointer.

In Docker deployments, back up the bind-mounted host paths rather than the container filesystem.

Restarting services

To restart a single service (local deployment):

make stop
make dev

Individual service restart scripts are in scripts/. For targeted restarts, you can kill and relaunch individual processes manually using the PIDs in the log files.