{"record":{"id":"fa08b54f4b07831b","repo":"langchain-ai/deepagents","slug":"prefix-args-must-be-a-list-got-type-args-na","errorCode":null,"errorMessage":"{prefix}.args must be a list, got {type(args).__name__}","messagePattern":"(.+?)\\.args must be a list, got (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/mcp_config.py","lineNumber":161,"sourceCode":"\n    Raises:\n        TypeError: If a supported field has the wrong type — a non-string\n            scalar value, or `args`/`env`/`headers` with the wrong container\n            type.\n        RuntimeError: If a required environment variable is unset.\n    \"\"\"  # noqa: DOC502 - `RuntimeError` is raised by `_interpolate_env`\n    resolved: dict[str, Any] = copy.deepcopy(dict(server_config))\n    prefix = f\"mcpServers.{server_name}\"\n\n    for name in (\"command\", \"url\"):\n        if name in resolved:\n            resolved[name] = _resolve_string(resolved[name], field=f\"{prefix}.{name}\")\n\n    if \"args\" in resolved:\n        args = resolved[\"args\"]\n        if not isinstance(args, list):\n            msg = f\"{prefix}.args must be a list, got {type(args).__name__}\"\n            raise TypeError(msg)\n        resolved[\"args\"] = [\n            _resolve_string(value, field=f\"{prefix}.args[{index}]\")\n            for index, value in enumerate(args)\n        ]\n\n    for name in (\"env\", \"headers\"):\n        if name not in resolved:\n            continue\n        values = resolved[name]\n        if not isinstance(values, dict):\n            msg = f\"{prefix}.{name} must be a dictionary, got {type(values).__name__}\"\n            raise TypeError(msg)\n        resolved[name] = _resolve_mapping_values(values, field=f\"{prefix}.{name}\")\n\n    return resolved\n","sourceCodeStart":143,"sourceCodeEnd":177,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/mcp_config.py#L143-L177","documentation":"`resolve_mcp_server_env` requires the `args` field of an MCP server entry to be a list; each element is then validated and env-interpolated as a string. If `args` is any other container type (string, dict, tuple), `TypeError` is raised naming the server path and the actual type.","triggerScenarios":"Calling `resolve_mcp_server_env` (directly, via login, `/mcp connect` preflight, or header resolution) with a server config where `args` is a string or object instead of a JSON array, e.g. `args: \"-y @model/server\"` or `args: {\"0\": \"-y\"}`.","commonSituations":"Hand-editing `mcpServers` entries and writing args as a single space-joined string; copying a Docker `CMD`-style config that uses a dict; converting configs from tools that serialize args differently; YAML configs where args collapsed to a scalar.","solutions":["Change `args` to a JSON list of strings: `\"args\": [\"-y\", \"@model/server\"]`.","If args came as one string, split it into list elements rather than relying on shell splitting (no shell word-splitting is performed).","Validate the server entry's shape before connecting — every element must also be a string (see error `mcpServers.<name>.args[i] must be a string`)."],"exampleFix":"// before\n{\"command\": \"npx\", \"args\": \"-y @modelcontextprotocol/server-everything\"}\n// after\n{\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-everything\"]}","handlingStrategy":"type-guard","validationCode":"def check_args(cfg: dict) -> str | None:\n    if \"args\" in cfg and not isinstance(cfg[\"args\"], list):\n        return f\"args must be a list, got {type(cfg['args']).__name__}\"\n    return None","typeGuard":"def is_str_list(v: object) -> TypeGuard[list[str]]:\n    return isinstance(v, list) and all(isinstance(x, str) for x in v)","tryCatchPattern":"try:\n    resolved = resolve_mcp_server_env(server_name, server_config)\nexcept TypeError as exc:\n    if \".args must be a list\" in str(exc):\n        raise SystemExit(f\"Fix {server_name}: wrap args in a JSON array\") from exc\n    raise","preventionTips":["Always write args as a JSON array of strings, never a single space-joined string","If migrating from a shell-command string, split it into list elements yourself (no shell splitting happens)","Validate the whole mcpServers entry shape before connecting; each args element must also be a string"],"tags":["mcp","type-error","config-validation","stdio"],"backgroundTag":"schema-validation-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}