deer-flow/frontend/src/content/en/application/operations-and-troubleshooting.mdx

---
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.

<Cards num={2}>
  <Cards.Card
    title="Deployment Guide"
    href="/docs/application/deployment-guide"
  />
  <Cards.Card title="Configuration" href="/docs/application/configuration" />
</Cards>