{"record":{"id":"87c52a59bf8d12dd","repo":"langchain-ai/deepagents","slug":"persistent-server-env-overrides-must-use-the-serv","errorCode":null,"errorMessage":"persistent server env overrides must use the {SERVER_ENV_PREFIX!r} prefix","messagePattern":"persistent server env overrides must use the (.+?) prefix","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/client/launch/server.py","lineNumber":1194,"sourceCode":"        self._env_overrides.update(overrides)\n\n    def persist_env(self, **overrides: str) -> None:\n        \"\"\"Persist env var overrides for every future subprocess start.\n\n        Args:\n            **overrides: Key/value env var pairs that should be passed to all\n                future server subprocesses.\n\n        Raises:\n            ValueError: If an override is not an app-owned server env var.\n        \"\"\"\n        invalid = [key for key in overrides if not key.startswith(SERVER_ENV_PREFIX)]\n        if invalid:\n            msg = (\n                \"persistent server env overrides must use the \"\n                f\"{SERVER_ENV_PREFIX!r} prefix\"\n            )\n            raise ValueError(msg)\n        self._persistent_env_overrides.update(overrides)\n\n    async def restart(self, *, timeout: float = _HEALTH_TIMEOUT) -> None:  # noqa: ASYNC109\n        \"\"\"Restart the server process, reusing the existing config directory.\n\n        Stops the subprocess, then starts a new one. Any env overrides staged\n        via `update_env()` are applied within a `_scoped_env_overrides` context\n        manager so that failures automatically roll back the environment to the\n        last known-good state.\n\n        Args:\n            timeout: Max seconds to wait for the server to become healthy.\n\n        Raises:\n            asyncio.CancelledError: Either if the restart task is cancelled\n                (the blocking subprocess cleanup is awaited to completion\n                first), or if a terminal `stop()` bumped the stop generation\n                during cleanup — in which case `_start` aborts rather than","sourceCodeStart":1176,"sourceCodeEnd":1212,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/client/launch/server.py#L1176-L1212","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the required prefix to every key: key must start with SERVER_ENV_PREFIX (e.g. `DEEPAGENTS_CODE_SERVER_...`)","Check SERVER_ENV_PREFIX in the launch module to build keys as f\"{SERVER_ENV_PREFIX}YOUR_KEY\"","If the variable is one-shot only (not needed across restarts), pass it via the startup env overrides instead of persist_env","Remove the offending keys from the overrides dict before retrying"],"exampleFix":"// before\nserver.persist_env({\"DB_PATH\": \"/tmp/x.db\"})  # ValueError\n// after\nserver.persist_env({f\"{SERVER_ENV_PREFIX}DB_PATH\": \"/tmp/x.db\"})","handlingStrategy":"validation","validationCode":"def valid_overrides(overrides, prefix):\n    bad = [k for k in overrides if not k.startswith(prefix)]\n    if bad:\n        raise ValueError(f\"keys missing {prefix!r} prefix: {bad}\")\n    return overrides\n\nserver.persist_env(valid_overrides(my_overrides, SERVER_ENV_PREFIX))","typeGuard":"def is_prefixed(key: str, prefix: str) -> bool:\n    return key.startswith(prefix)","tryCatchPattern":"try:\n    server.persist_env(overrides)\nexcept ValueError as e:\n    if \"prefix\" in str(e):\n        overrides = {f\"{SERVER_ENV_PREFIX}{k}\" if not k.startswith(SERVER_ENV_PREFIX) else k: v for k, v in overrides.items()}\n        server.persist_env(overrides)\n    else:\n        raise","preventionTips":["Build override keys with f\"{SERVER_ENV_PREFIX}...\" always","Keep one helper that constructs server env keys","Use persist_env only for keys that must survive restarts"],"tags":["validation","environment","valueerror"],"backgroundTag":"missing-env-prefix","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}