langchain-ai/deepagents · error · TypeError

{field} must be a string, got {type(value).__name__}

Error message

{field} must be a string, got {type(value).__name__}

What it means

`_resolve_string` validates that a supported MCP config field (`command`, `url`, an `args` element, or an `env`/`headers` value) is a string before interpolating env references. A non-string value raises `TypeError` naming the fully qualified field path and the actual type.

Source

Thrown at libs/code/deepagents_code/mcp_config.py:103

    return _ENV_REF_RE.sub(replace, value)


def _resolve_string(value: object, *, field: str) -> str:
    """Validate and interpolate one string field.

    Args:
        value: Raw field value.
        field: Fully qualified field path for error messages.

    Returns:
        The validated and interpolated string.

    Raises:
        TypeError: If the field value is not a string.
    """
    if not isinstance(value, str):
        msg = f"{field} must be a string, got {type(value).__name__}"
        raise TypeError(msg)
    return _interpolate_env(value, field=field)


def _resolve_mapping_values(
    values: Mapping[str, object],
    *,
    field: str,
) -> dict[str, str]:
    """Validate and interpolate string values in a mapping field.

    Args:
        values: Raw mapping values.
        field: Fully qualified field path for error messages.

    Returns:
        A new mapping with validated and interpolated values.
    """
    return {

View on GitHub (pinned to a1af029e6e)

Solutions

1. Quote the field value as a string in the config (`port: "8080"`).
2. Fix the code path building the config to stringify values (`str(value)`).
3. Check the field named in the message — it identifies the exact path, e.g. `mcpServers.myserver.args[2]`.

Example fix

// before
{"env": {"PORT": 8080}}
// after
{"env": {"PORT": "8080"}}

SUPPORTED_FIELDS = ("command", "url")
def check_string_fields(cfg: dict) -> list[str]:
    errs = []
    for f in SUPPORTED_FIELDS:
        if f in cfg and not isinstance(cfg[f], str):
            errs.append(f"{f} must be a string, got {type(cfg[f]).__name__}")
    for f in ("env", "headers"):
        for k, v in cfg.get(f, {}).items():
            if not isinstance(v, str):
                errs.append(f"{f}.{k} must be a string, got {type(v).__name__}")
    return errs

def is_str_field(v: object) -> TypeGuard[str]:
    return isinstance(v, str)

try:
    resolved = resolve_mcp_server_env(server_name, server_config)
except TypeError as exc:
    raise SystemExit(f"Config type error: {exc} — quote the field as a string") from exc

When it happens

Trigger: Calling `resolve_mcp_server_env(server_name, server_config)` where a supported field holds a non-string: e.g. `url: 123`, an `args` element that is a number/bool/dict, or an `env` value that is `true`/`null`.

Common situations: JSON/YAML configs where numbers or booleans are unquoted (`port: 8080`, `verbose: true`); programmatic config construction passing ints or `None`; schema drift after the server entry was edited by hand or generated by a tool.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {prefix}.args must be a list, got {type(args).__name__}
• {str(exc)}
• {field} references unset env var {name}. Set {name} in the e
• {field} contains a malformed '${{...}}' reference. Use '${VA
• {prefix}.{name} must be a dictionary, got {type(values).__na

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