bytedance/deer-flow · critical · SystemExit

agent_storage.backend='db' requires database.backend to be '

Error message

agent_storage.backend='db' requires database.backend to be 'sqlite' or 'postgres', but database.backend is '{db_backend}'. A 'memory' database is per-process and cannot share agent definitions across nodes. Set database.backend, or use agent_storage.backend='file'.

What it means

SystemExit raised at startup when agent_storage.backend='db' but database.backend is not sqlite or postgres (i.e. memory). A 'memory' database is per-process with no shareable SQL URL, so agent definitions would silently diverge across nodes; the gate mirrors deermem's create_storage fail-fast. A companion warning (not fatal) fires when multi-worker Postgres leaves agent storage on 'file', because file storage is per-node disk.

Source

Thrown at backend/app/gateway/deps.py:147

def _validate_agent_storage(config: AppConfig) -> None:
    """Fail fast on an agent-storage backend the database cannot support.

    ``agent_storage.backend: db`` needs a durable, shared SQL database — a
    ``memory`` database is per-process, so agent definitions would silently
    diverge across nodes (and there is no SQL URL to open). Mirrors deermem's
    create_storage fail-fast and the multi-worker gate above.

    Also warns when a multi-worker Postgres deployment leaves agent storage on
    ``file``: custom agents created on one node's local disk are invisible to
    the others, exactly the divergence the db backend exists to fix.
    """
    agent_storage = getattr(config, "agent_storage", None)
    backend = getattr(agent_storage, "backend", "file")
    db_backend = getattr(getattr(config, "database", None), "backend", None)
    if backend == "db" and db_backend not in ("sqlite", "postgres"):
        raise SystemExit(
            f"agent_storage.backend='db' requires database.backend to be 'sqlite' or 'postgres', "
            f"but database.backend is '{db_backend}'. A 'memory' database is per-process and cannot "
            "share agent definitions across nodes. Set database.backend, or use agent_storage.backend='file'."
        )
    try:
        workers = int(os.environ.get("GATEWAY_WORKERS", "1"))
    except (TypeError, ValueError):
        workers = 1
    if workers > 1 and db_backend == "postgres" and backend == "file":
        logger.warning(
            "GATEWAY_WORKERS=%s with database.backend='postgres' but agent_storage.backend='file': custom agents are stored per-node on local disk and are not visible across workers/nodes. Set agent_storage.backend='db' to share them.",
            workers,
        )


async def _drain_inflight_runs(run_manager: RunManager) -> None:
    """Drain in-flight runs before the checkpointer is torn down (issue #3373).

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Set database.backend to sqlite or postgres in config.yaml
2. Or set agent_storage.backend: file if sharing across nodes is not needed
3. If running multi-worker Postgres on file storage, switch agent_storage.backend: db to avoid the per-node divergence warning

Example fix

# config.yaml
# before
database:
  backend: memory
agent_storage:
  backend: db
# after
database:
  backend: postgres
agent_storage:
  backend: db

cfg = load_config()
as_backend = getattr(getattr(cfg, "agent_storage", None), "backend", "file")
db_backend = getattr(getattr(cfg, "database", None), "backend", None)
assert not (as_backend == "db" and db_backend not in ("sqlite", "postgres")), "agent_storage db needs a real SQL backend"

When it happens

Trigger: config.yaml with agent_storage.backend: db and database.backend: memory; typically reached on startup right after the multi-worker gates.

Common situations: Test/ephemeral deployments using database.backend: memory that opt into DB-backed agent storage; partial config migrations where agent_storage was set but the database section was left default.

Related errors

• scheduler.multi_instance=true requires database.backend='pos
• scheduler.multi_instance=true requires run_events.backend='d
• scheduler.multi_instance=true requires run_ownership.heartbe
• GATEWAY_WORKERS={workers} cannot run with scheduler.enabled=
• GATEWAY_WORKERS={workers} cannot enable agentic browser tool

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/8297e720213cfcbb. Report an issue: GitHub.