langchain-ai/deepagents · critical · RuntimeError

{db_path_var} not set. The app must set this env var before

Error message

{db_path_var} not set. The app must set this env var before server startup.

What it means

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.

Source

Thrown at libs/code/deepagents_code/client/launch/server_manager.py:156

"""Persistent SQLite checkpointer for the LangGraph dev server."""

import os
from contextlib import asynccontextmanager


@asynccontextmanager
async def create_checkpointer():
    """Yield an AsyncSqliteSaver connected to the app's sessions DB.

    The database path is read from the `{db_path_var}` env var
    (set by the app before server startup) rather than hard-coded, so
    the checkpointer module works without code generation.
    """
    from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver

    db_path = os.environ.get("{db_path_var}")
    if not db_path:
        raise RuntimeError(
            "{db_path_var} not set. The app must set this "
            "env var before server startup."
        )
    async with AsyncSqliteSaver.from_conn_string(db_path) as saver:
        yield saver
'''
    (work_dir / "checkpointer.py").write_text(content)


def _write_pyproject(work_dir: Path) -> None:
    """Write a minimal pyproject.toml for the server working directory.

    The `langgraph dev` server needs to install the project dependencies.
    We point it at the app package which transitively pulls in the SDK.

    Args:
        work_dir: Server working directory.
    """

View on GitHub (pinned to a1af029e6e)

Solutions

1. Export/set `DEEPAGENTS_CODE_SERVER_DB_PATH` (whatever SERVER_ENV_PREFIX resolves to + `DB_PATH`) before server startup
2. Use the library's normal launch path (`start_server_and_get_agent`) so `_write_checkpointer` seeds the var automatically
3. If respawning, ensure persist_env does not drop or overwrite the DB_PATH key
4. Check the sessions DB path resolution (`get_db_path`) succeeds so the var is set to a valid path

Example fix

// before
$ langgraph dev  # server env scrubbed -> RuntimeError ... not set
// after
$ export DEEPAGENTS_CODE_SERVER_DB_PATH=$HOME/.dcode/sessions.db && langgraph dev

import os
db_var = f"{SERVER_ENV_PREFIX}DB_PATH"
if not os.environ.get(db_var):
    raise RuntimeError(f"{db_var} must be set before server startup")

try:
    async for saver in create_checkpointer():
        ...
except RuntimeError as e:
    if "not set" in str(e):
        os.environ[db_var] = str(get_db_path())  # re-seed and retry
    else:
        raise

When it happens

Trigger: 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`.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• dcode: {message}
• Could not determine the home directory: set $HOME, or set DE
• Home directory is not absolute: {launch_home}. Set $HOME to
• Invalid DEEPAGENTS_HOME {configured!r}: use an absolute path
• Failed to parse {SERVER_ENV_PREFIX}{suffix} as JSON: {exc}.

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/34e556bfaa7e5391. Report an issue: GitHub.