{"record":{"id":"34e556bfaa7e5391","repo":"langchain-ai/deepagents","slug":"db-path-var-not-set-the-app-must-set-this-env-v","errorCode":null,"errorMessage":"{db_path_var} not set. The app must set this env var before server startup.","messagePattern":"(.+?) not set\\. The app must set this env var before server startup\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"libs/code/deepagents_code/client/launch/server_manager.py","lineNumber":156,"sourceCode":"\"\"\"Persistent SQLite checkpointer for the LangGraph dev server.\"\"\"\n\nimport os\nfrom contextlib import asynccontextmanager\n\n\n@asynccontextmanager\nasync def create_checkpointer():\n    \"\"\"Yield an AsyncSqliteSaver connected to the app's sessions DB.\n\n    The database path is read from the `{db_path_var}` env var\n    (set by the app before server startup) rather than hard-coded, so\n    the checkpointer module works without code generation.\n    \"\"\"\n    from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver\n\n    db_path = os.environ.get(\"{db_path_var}\")\n    if not db_path:\n        raise RuntimeError(\n            \"{db_path_var} not set. The app must set this \"\n            \"env var before server startup.\"\n        )\n    async with AsyncSqliteSaver.from_conn_string(db_path) as saver:\n        yield saver\n'''\n    (work_dir / \"checkpointer.py\").write_text(content)\n\n\ndef _write_pyproject(work_dir: Path) -> None:\n    \"\"\"Write a minimal pyproject.toml for the server working directory.\n\n    The `langgraph dev` server needs to install the project dependencies.\n    We point it at the app package which transitively pulls in the SDK.\n\n    Args:\n        work_dir: Server working directory.\n    \"\"\"","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/client/launch/server_manager.py#L138-L174","documentation":"The generated checkpointer module (written into the server work dir by `_write_checkpointer`) reads the SQLite DB path from the `{SERVER_ENV_PREFIX}DB_PATH` env var at runtime rather than hardcoding it. If the var is unset when `create_checkpointer()` runs inside the server process, it raises this RuntimeError. Normally the app sets this var before spawning the server, so hitting it means the var was lost between parent and subprocess.","triggerScenarios":"The server subprocess starts without the `{SERVER_ENV_PREFIX}DB_PATH` env var — e.g. env overrides dropped the var, a custom launch path skips `_write_checkpointer`'s `os.environ[...] = ...` seeding, or the var was cleared in a restricted/subclean environment. Raised by `_write_checkpointer`'s generated code, called during `_scaffold_workspace`.","commonSituations":"Launching the server with a scrubbed/filtered env; a respawn where persistent overrides replaced the DB_PATH var; running the generated checkpointer.py standalone in a different process without exporting the var.","solutions":["Export/set `DEEPAGENTS_CODE_SERVER_DB_PATH` (whatever SERVER_ENV_PREFIX resolves to + `DB_PATH`) before server startup","Use the library's normal launch path (`start_server_and_get_agent`) so `_write_checkpointer` seeds the var automatically","If respawning, ensure persist_env does not drop or overwrite the DB_PATH key","Check the sessions DB path resolution (`get_db_path`) succeeds so the var is set to a valid path"],"exampleFix":"// before\n$ langgraph dev  # server env scrubbed -> RuntimeError ... not set\n// after\n$ export DEEPAGENTS_CODE_SERVER_DB_PATH=$HOME/.dcode/sessions.db && langgraph dev","handlingStrategy":"validation","validationCode":"import os\ndb_var = f\"{SERVER_ENV_PREFIX}DB_PATH\"\nif not os.environ.get(db_var):\n    raise RuntimeError(f\"{db_var} must be set before server startup\")","typeGuard":null,"tryCatchPattern":"try:\n    async for saver in create_checkpointer():\n        ...\nexcept RuntimeError as e:\n    if \"not set\" in str(e):\n        os.environ[db_var] = str(get_db_path())  # re-seed and retry\n    else:\n        raise","preventionTips":["Launch the server via the library's start API, which seeds the var","Do not scrub/filter env vars when spawning the server subprocess","When running the generated checkpointer manually, export the var first"],"tags":["environment","sqlite","checkpointer"],"backgroundTag":"missing-env-var","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}