langchain-ai/deepagents · error · ValueError

persistent server env overrides must use the {SERVER_ENV_PRE

Error message

persistent server env overrides must use the {SERVER_ENV_PREFIX!r} prefix

What it means

`persist_env` stages environment overrides that must survive server restarts. Because persisted keys are re-applied on every respawn, the API requires them to carry the `SERVER_ENV_PREFIX` (the `DEEPAGENTS_CODE_SERVER_`-style prefix) so they are unambiguously server-scoped. Passing any key without that prefix raises this ValueError listing nothing until the offending keys are removed.

Source

Thrown at libs/code/deepagents_code/client/launch/server.py:1194

        self._env_overrides.update(overrides)

    def persist_env(self, **overrides: str) -> None:
        """Persist env var overrides for every future subprocess start.

        Args:
            **overrides: Key/value env var pairs that should be passed to all
                future server subprocesses.

        Raises:
            ValueError: If an override is not an app-owned server env var.
        """
        invalid = [key for key in overrides if not key.startswith(SERVER_ENV_PREFIX)]
        if invalid:
            msg = (
                "persistent server env overrides must use the "
                f"{SERVER_ENV_PREFIX!r} prefix"
            )
            raise ValueError(msg)
        self._persistent_env_overrides.update(overrides)

    async def restart(self, *, timeout: float = _HEALTH_TIMEOUT) -> None:  # noqa: ASYNC109
        """Restart the server process, reusing the existing config directory.

        Stops the subprocess, then starts a new one. Any env overrides staged
        via `update_env()` are applied within a `_scoped_env_overrides` context
        manager so that failures automatically roll back the environment to the
        last known-good state.

        Args:
            timeout: Max seconds to wait for the server to become healthy.

        Raises:
            asyncio.CancelledError: Either if the restart task is cancelled
                (the blocking subprocess cleanup is awaited to completion
                first), or if a terminal `stop()` bumped the stop generation
                during cleanup — in which case `_start` aborts rather than

View on GitHub (pinned to a1af029e6e)

Solutions

1. Add the required prefix to every key: key must start with SERVER_ENV_PREFIX (e.g. `DEEPAGENTS_CODE_SERVER_...`)
2. Check SERVER_ENV_PREFIX in the launch module to build keys as f"{SERVER_ENV_PREFIX}YOUR_KEY"
3. If the variable is one-shot only (not needed across restarts), pass it via the startup env overrides instead of persist_env
4. Remove the offending keys from the overrides dict before retrying

Example fix

// before
server.persist_env({"DB_PATH": "/tmp/x.db"})  # ValueError
// after
server.persist_env({f"{SERVER_ENV_PREFIX}DB_PATH": "/tmp/x.db"})

def valid_overrides(overrides, prefix):
    bad = [k for k in overrides if not k.startswith(prefix)]
    if bad:
        raise ValueError(f"keys missing {prefix!r} prefix: {bad}")
    return overrides

server.persist_env(valid_overrides(my_overrides, SERVER_ENV_PREFIX))

def is_prefixed(key: str, prefix: str) -> bool:
    return key.startswith(prefix)

try:
    server.persist_env(overrides)
except ValueError as e:
    if "prefix" in str(e):
        overrides = {f"{SERVER_ENV_PREFIX}{k}" if not k.startswith(SERVER_ENV_PREFIX) else k: v for k, v in overrides.items()}
        server.persist_env(overrides)
    else:
        raise

When it happens

Trigger: Calling `persist_env({...})` with keys lacking the required prefix — e.g. persist_env({"API_KEY": "..."}) or {"MODEL_NAME": ...} instead of the prefixed names. Called by `_set_rubric_max_iterations` internally; user/test callers hit it with hand-built dicts.

Common situations: Typo or forgotten prefix when persisting server config; copying raw env-var names from docs without the server prefix; refactors that rename keys without updating the prefix convention.

Related errors

• Could not parse embedded resource block. Block expected eith
• question text must not be blank
• choice has a blank 'value': {choice!r}
• {question_type} question {question_text!r} requires a non-em
• {question_type} question {question_text!r} must not define '

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