{"record":{"id":"8297e720213cfcbb","repo":"bytedance/deer-flow","slug":"agent-storage-backend-db-requires-database-backe","errorCode":null,"errorMessage":"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'.","messagePattern":"agent_storage\\.backend='db' requires database\\.backend to be 'sqlite' or 'postgres', but database\\.backend is '(.+?)'\\. A 'memory' database is per-process and cannot share agent definitions across nodes\\. Set database\\.backend, or use agent_storage\\.backend='file'\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"critical","filePath":"backend/app/gateway/deps.py","lineNumber":147,"sourceCode":"\n\ndef _validate_agent_storage(config: AppConfig) -> None:\n    \"\"\"Fail fast on an agent-storage backend the database cannot support.\n\n    ``agent_storage.backend: db`` needs a durable, shared SQL database — a\n    ``memory`` database is per-process, so agent definitions would silently\n    diverge across nodes (and there is no SQL URL to open). Mirrors deermem's\n    create_storage fail-fast and the multi-worker gate above.\n\n    Also warns when a multi-worker Postgres deployment leaves agent storage on\n    ``file``: custom agents created on one node's local disk are invisible to\n    the others, exactly the divergence the db backend exists to fix.\n    \"\"\"\n    agent_storage = getattr(config, \"agent_storage\", None)\n    backend = getattr(agent_storage, \"backend\", \"file\")\n    db_backend = getattr(getattr(config, \"database\", None), \"backend\", None)\n    if backend == \"db\" and db_backend not in (\"sqlite\", \"postgres\"):\n        raise SystemExit(\n            f\"agent_storage.backend='db' requires database.backend to be 'sqlite' or 'postgres', \"\n            f\"but database.backend is '{db_backend}'. A 'memory' database is per-process and cannot \"\n            \"share agent definitions across nodes. Set database.backend, or use agent_storage.backend='file'.\"\n        )\n    try:\n        workers = int(os.environ.get(\"GATEWAY_WORKERS\", \"1\"))\n    except (TypeError, ValueError):\n        workers = 1\n    if workers > 1 and db_backend == \"postgres\" and backend == \"file\":\n        logger.warning(\n            \"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.\",\n            workers,\n        )\n\n\nasync def _drain_inflight_runs(run_manager: RunManager) -> None:\n    \"\"\"Drain in-flight runs before the checkpointer is torn down (issue #3373).\n","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/bytedance/deer-flow/blob/1dd6ba1acb03700589994b0366c5d1c7d05e2eff/backend/app/gateway/deps.py#L129-L165","documentation":"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.","triggerScenarios":"config.yaml with agent_storage.backend: db and database.backend: memory; typically reached on startup right after the multi-worker gates.","commonSituations":"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.","solutions":["Set database.backend to sqlite or postgres in config.yaml","Or set agent_storage.backend: file if sharing across nodes is not needed","If running multi-worker Postgres on file storage, switch agent_storage.backend: db to avoid the per-node divergence warning"],"exampleFix":"# config.yaml\n# before\ndatabase:\n  backend: memory\nagent_storage:\n  backend: db\n# after\ndatabase:\n  backend: postgres\nagent_storage:\n  backend: db","handlingStrategy":"validation","validationCode":"cfg = load_config()\nas_backend = getattr(getattr(cfg, \"agent_storage\", None), \"backend\", \"file\")\ndb_backend = getattr(getattr(cfg, \"database\", None), \"backend\", None)\nassert not (as_backend == \"db\" and db_backend not in (\"sqlite\", \"postgres\")), \"agent_storage db needs a real SQL backend\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pair agent_storage.backend: db with database.backend sqlite (single node) or postgres (shared)","On multi-worker postgres, prefer agent_storage.backend: db to avoid per-node file divergence","Lint config for backend-combination rules in CI (memory database + db storage is always invalid)"],"tags":["config","startup","agent-storage","database","system-exit","gateway"],"backgroundTag":null,"analyzedSha":"1dd6ba1acb03700589994b0366c5d1c7d05e2eff","analyzedAt":"2026-08-14T21:20:34.804Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}