langchain-ai/deepagents · error · TypeError

Server '{server_name}' 'env' must be a dictionary

Error message

Server '{server_name}' 'env' must be a dictionary

What it means

For stdio servers, `env` supplies environment variables to the child process and must be a dictionary of string names to string values. `_validate_server_config` raises this TypeError when `env` is present but is not a dict (e.g. a list or string), because the subprocess environment can only be built from a mapping.

Source

Thrown at libs/code/deepagents_code/mcp_tools.py:927

        if "command" not in server_config:
            error_msg = f"Server '{server_name}' missing required 'command' field"
            raise ValueError(error_msg)

        if "url" in server_config:
            error_msg = (
                f"Server '{server_name}' has type 'stdio' but also declares "
                "a 'url' field. Remove 'url' or set "
                '`"type": "http"` (or `"sse"`) for a remote server.'
            )
            raise ValueError(error_msg)

        if "args" in server_config and not isinstance(server_config["args"], list):
            error_msg = f"Server '{server_name}' 'args' must be a list"
            raise TypeError(error_msg)

        if "env" in server_config and not isinstance(server_config["env"], dict):
            error_msg = f"Server '{server_name}' 'env' must be a dictionary"
            raise TypeError(error_msg)
    else:
        error_msg = (
            f"Server '{server_name}' has unsupported transport type '{server_type}'. "
            "Supported types: stdio, sse, http"
        )
        raise ValueError(error_msg)

    auth = server_config.get("auth")
    if auth is not None:
        if auth != "oauth":
            msg = (
                f"Server '{server_name}' has unsupported auth value "
                f"{auth!r}. Only 'oauth' is supported."
            )
            raise ValueError(msg)
        if server_type == "stdio":
            msg = (
                f"Server '{server_name}' uses stdio transport; "

View on GitHub (pinned to a1af029e6e)

Solutions

1. Convert `env` to a dictionary: {"KEY": "value", ...}.
2. Parse a 'KEY=value' string/list into a dict by splitting on the first '=' before assigning.
3. Omit `env` if no custom environment variables are needed (it is optional; parent env is inherited).
4. Validate env values are strings where required by the child process.

Example fix

// before
"env": "API_KEY=abc DEBUG=1"
// after
"env": {"API_KEY": "abc", "DEBUG": "1"}

def validate_env(name: str, cfg: dict) -> None:
    env = cfg.get("env")
    if env is not None and not (isinstance(env, dict) and all(isinstance(v, str) for v in env.values())):
        raise TypeError(f"Server '{name}' 'env' must be a dictionary of string values")

def has_valid_env(cfg: dict) -> bool:
    env = cfg.get("env")
    return env is None or (isinstance(env, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in env.items()))

try:
    tools = resolve_and_load_mcp_tools(config)
except TypeError as e:
    if "'env' must be a dictionary" in str(e):
        name = extract_server_name(str(e))
        raw = config["servers"][name].get("env")
        pairs = raw.split() if isinstance(raw, str) else raw
        config["servers"][name]["env"] = dict(p.split("=", 1) for p in pairs)
        tools = resolve_and_load_mcp_tools(config)
    else:
        raise

When it happens

Trigger: A stdio server entry has `env` as a non-dict — e.g. `"env": "API_KEY=abc"` or `"env": ["A=1", "B=2"]` — validated via `select_server`, `resolve_and_load_mcp_tools`, or the batch config validators.

Common situations: Authoring env as a shell-style 'KEY=value' string or list from a Docker/CLI habit; YAML producing a list from sequence syntax; copying `headers`-style list config into `env`; programmatically joining env entries with newlines.

Related errors

• Server '{server_name}' 'args' must be a list
• {prefix}.args must be a list, got {type(args).__name__}
• Server '{server_name}' 'headers' must be a dictionary
• Server '{server_name}' header {name!r} must be a string, got
• Server '{server_name}' missing required 'command' field

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