--- 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: ```bash tail -f logs/gateway.log ``` Adjust the runtime log level in `config.yaml`: ```yaml log_level: debug # debug | info | warning | error ``` ## Health checks Verify each service is responding: ```bash # 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: ```bash 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: ```yaml 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): ```bash 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.