{"record":{"id":"983adfdffda602ea","repo":"langchain-ai/deepagents","slug":"server-server-name-header-name-r-must-be-a-s","errorCode":null,"errorMessage":"Server '{server_name}' header {name!r} must be a string, got {type(value).__name__}","messagePattern":"Server '(.+?)' header (.+?) must be a string, got (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/mcp_tools.py","lineNumber":907,"sourceCode":"                f\"Server '{server_name}' has type '{server_type}' (remote) \"\n                \"but also declares a 'command' field. Remove 'command' or \"\n                'set `\"type\": \"stdio\"`.'\n            )\n            raise ValueError(error_msg)\n\n        headers = server_config.get(\"headers\")\n        if headers is not None and not isinstance(headers, dict):\n            error_msg = f\"Server '{server_name}' 'headers' must be a dictionary\"\n            raise TypeError(error_msg)\n\n        if isinstance(headers, dict):\n            for name, value in headers.items():\n                if not isinstance(value, str):\n                    error_msg = (\n                        f\"Server '{server_name}' header {name!r} must be \"\n                        f\"a string, got {type(value).__name__}\"\n                    )\n                    raise TypeError(error_msg)\n    elif server_type == \"stdio\":\n        if \"command\" not in server_config:\n            error_msg = f\"Server '{server_name}' missing required 'command' field\"\n            raise ValueError(error_msg)\n\n        if \"url\" in server_config:\n            error_msg = (\n                f\"Server '{server_name}' has type 'stdio' but also declares \"\n                \"a 'url' field. Remove 'url' or set \"\n                '`\"type\": \"http\"` (or `\"sse\"`) for a remote server.'\n            )\n            raise ValueError(error_msg)\n\n        if \"args\" in server_config and not isinstance(server_config[\"args\"], list):\n            error_msg = f\"Server '{server_name}' 'args' must be a list\"\n            raise TypeError(error_msg)\n\n        if \"env\" in server_config and not isinstance(server_config[\"env\"], dict):","sourceCodeStart":889,"sourceCodeEnd":925,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/mcp_tools.py#L889-L925","documentation":"HTTP header values sent to remote MCP servers must be strings. `_validate_server_config` iterates each `headers` entry for http/sse servers and raises this TypeError when any value is a non-string (int, dict, list, bool, None, etc.), since HTTP headers are serialized as text and cannot carry structured values.","triggerScenarios":"A server entry of type `http`/`sse` has `headers` as a dict but at least one value is not a string, e.g. `{\"X-Retries\": 3}` or `{\"X-Debug\": true}`, validated via `select_server`, `resolve_and_load_mcp_tools`, or the batch validators.","commonSituations":"Numeric header values like port or version numbers written unquoted in YAML (YAML auto-types `3` as int); boolean flags as header values; JSON where a token was accidentally nested as an object; templated headers that resolved to None.","solutions":["Convert each header value to a string, e.g. {\"X-Retries\": \"3\"} instead of 3.","Quote values in YAML config files so the parser keeps them as strings.","Remove non-string values and pass such data via `env` (stdio) or query parameters instead.","Wrap potentially non-string values with str(...) when building headers programmatically."],"exampleFix":"// before\n\"headers\": {\"X-Retries\": 3, \"Authorization\": token_or_none}\n// after\n\"headers\": {\"X-Retries\": \"3\", \"Authorization\": str(token_or_none or \"\")}","handlingStrategy":"type-guard","validationCode":"def validate_header_values(name: str, cfg: dict) -> None:\n    headers = cfg.get(\"headers\")\n    if isinstance(headers, dict):\n        for k, v in headers.items():\n            if not isinstance(v, str):\n                raise TypeError(f\"Server '{name}' header {k!r} must be a string, got {type(v).__name__}\")","typeGuard":"def has_string_headers(cfg: dict) -> bool:\n    h = cfg.get(\"headers\")\n    return h is None or (isinstance(h, dict) and all(isinstance(v, str) for v in h.values()))","tryCatchPattern":"try:\n    tools = resolve_and_load_mcp_tools(config)\nexcept TypeError as e:\n    if \"must be a string\" in str(e):\n        server_cfg = config[\"servers\"][extract_server_name(str(e))]\n        server_cfg[\"headers\"] = {k: str(v) for k, v in server_cfg.get(\"headers\", {}).items()}\n        tools = resolve_and_load_mcp_tools(config)\n    else:\n        raise","preventionTips":["Quote header values in YAML so parsers do not coerce numbers/booleans to int/bool.","Coerce with str(...) when building headers programmatically from config or env.","Never put structured data (objects, lists) into header values; HTTP headers are text.","Lint MCP config files for header value types."],"tags":["mcp","config-validation","typeerror","http-headers"],"backgroundTag":"mcp-server-config-invalid","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}