langchain-ai/deepagents · error · ValueError

Failed to parse {SERVER_ENV_PREFIX}{suffix} as JSON: {exc}.

Error message

Failed to parse {SERVER_ENV_PREFIX}{suffix} as JSON: {exc}. Value was: {raw[:200]!r}

What it means

`_read_env_json` in `libs/code/deepagents_code/_server_config.py` raises this `ValueError` when a `DEEPAGENTS_CODE_SERVER_*` environment variable is present but its value is not valid JSON. The server subprocess reads structured configuration (string lists, booleans with JSON shapes, allowlists) from the environment, and the message includes the parser error plus the first 200 characters of the raw value to make the offending input diagnosable. It fails closed because some of these variables are security controls.

Source

Thrown at libs/code/deepagents_code/_server_config.py:70

        suffix: Variable name suffix after the `DEEPAGENTS_CODE_SERVER_` prefix.

    Returns:
        Parsed JSON value, or `None` if the variable is absent.

    Raises:
        ValueError: If the variable is present but not valid JSON.
    """
    raw = os.environ.get(f"{SERVER_ENV_PREFIX}{suffix}")
    if raw is None:
        return None
    try:
        return json.loads(raw)
    except json.JSONDecodeError as exc:
        msg = (
            f"Failed to parse {SERVER_ENV_PREFIX}{suffix} as JSON: {exc}. "
            f"Value was: {raw[:200]!r}"
        )
        raise ValueError(msg) from exc


def _read_env_str_list(suffix: str) -> tuple[str, ...]:
    raw = _read_env_json(suffix)
    if raw is None:
        return ()
    if isinstance(raw, list) and all(isinstance(item, str) for item in raw):
        return tuple(raw)
    msg = f"Invalid {SERVER_ENV_PREFIX}{suffix}: expected a JSON string list"
    raise ValueError(msg)


def _read_env_allow_fs_tools() -> list[FsToolName] | None:
    """Read and shape-validate the `ALLOW_FS_TOOLS` filesystem allowlist.

    The parent writes only an absent variable (unrestricted — `None`, which is
    also what `--allow-fs-tools all` collapses to) or a non-empty JSON list of
    tool names (`main._parse_allow_fs_tools_flag`). This runs in the server

View on GitHub (pinned to a1af029e6e)

Solutions

Set the variable to valid JSON, e.g. `export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='["grep","glob"]'` (single-quote so the shell preserves double quotes).
Validate locally first: `python -c "import json,os;json.loads(os.environ['DEEPAGENTS_CODE_SERVER_...'])"` to confirm the exact value parses.
Check the raw value shown in the error message (`Value was: ...`) for shell quote-stripping, truncation, or embedded newlines.
Unset the variable to fall back to the default behavior if you did not intend to configure it.
Fix the parent/launcher code that writes the variable so it JSON-encodes with `json.dumps` before export.

Example fix

// before (shell)
export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS=grep,glob
// after (shell)
export DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS='["grep","glob"]'

Defensive patterns

Strategy: validation

Validate before calling

import json, os

def env_json_valid(suffix: str) -> bool:
    raw = os.environ.get(f"DEEPAGENTS_CODE_SERVER_{suffix}")
    if raw is None:
        return True
    try:
        json.loads(raw)
        return True
    except json.JSONDecodeError:
        return False

Type guard

def is_json_object(raw: str) -> bool:
    try:
        return isinstance(json.loads(raw), object)
    except json.JSONDecodeError:
        return False

Try / catch

try:
    config = ServerConfig.from_env()
except ValueError as exc:
    raise ConfigError(f"malformed DEEPAGENTS_CODE_SERVER_* variable: {exc}") from exc

Prevention

Build env values with json.dumps() in the launching process, never by string formatting.
Single-quote JSON in shell so inner double quotes survive.
Test-parse every DEEPAGENTS_CODE_SERVER_* variable in CI before spawning the server.
Read the 'Value was:' excerpt in the error to spot shell quote-stripping or truncation.

When it happens

Trigger: Setting `DEEPAGENTS_CODE_SERVER_*` variables (e.g. `DEEPAGENTS_CODE_SERVER_ALLOW_FS_TOOLS` or any suffix consumed by `_read_env_json` via `_read_env_str_list`, `_read_env_allow_fs_tools`, or `ServerConfig.from_env`) to non-JSON text such as `grep,glob` (no JSON quotes/brackets), single-quoted JSON `'['a']'` where the shell strips quotes leaving bare `[a]`, or trailing commas/garbage.

Common situations: Hand-editing an exported variable in a shell profile without JSON-encoding it; a parent process writing the variable with an unescaped/undecoded payload; copy-pasting a Python list literal `[a, b]` (unquoted items) instead of a JSON array; template rendering inserting raw text into the value.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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