{"record":{"id":"542f90ed636ac29b","repo":"langchain-ai/deepagents","slug":"field-contains-a-malformed-reference","errorCode":null,"errorMessage":"{field} contains a malformed '${{...}}' reference. Use '${VAR}' or '${VAR:-default}'.","messagePattern":"(.+?) contains a malformed '(.+?)\\}' reference\\. Use '(.+?)' or '(.+?)'\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/mcp_config.py","lineNumber":83,"sourceCode":"            return resolved\n        # `${VAR}` unset with no default: the only hard error.\n        msg = (\n            f\"{field} references unset env var {name}. \"\n            f\"Set {name} in the environment or provide a default.\"\n        )\n        raise RuntimeError(msg)\n\n    # Reject any `${` that isn't the start of a well-formed reference. The\n    # check is against the raw `value` (not the substituted result) so a\n    # resolved value that happens to contain `${` never trips it.\n    ref_spans = [match.span() for match in _ENV_REF_RE.finditer(value)]\n    for brace in _ENV_BRACE_RE.finditer(value):\n        if not any(start <= brace.start() < end for start, end in ref_spans):\n            msg = (\n                f\"{field} contains a malformed '${{...}}' reference. \"\n                \"Use '${VAR}' or '${VAR:-default}'.\"\n            )\n            raise RuntimeError(msg)\n\n    return _ENV_REF_RE.sub(replace, value)\n\n\ndef _resolve_string(value: object, *, field: str) -> str:\n    \"\"\"Validate and interpolate one string field.\n\n    Args:\n        value: Raw field value.\n        field: Fully qualified field path for error messages.\n\n    Returns:\n        The validated and interpolated string.\n\n    Raises:\n        TypeError: If the field value is not a string.\n    \"\"\"\n    if not isinstance(value, str):","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/mcp_config.py#L65-L101","documentation":"`_interpolate_env` only accepts well-formed `${VAR}` or `${VAR:-default}` references. Any `${` in the raw value that does not match the reference regex (e.g. `${VAR-default}` with a single dash, `${my var}`, or an unterminated `${VAR`) is rejected with `RuntimeError` instead of being emitted verbatim, so a typo cannot inject garbage into a URL, command, or header.","triggerScenarios":"Calling `resolve_mcp_server_env` (via `_resolve_string` -> `_interpolate_env`) with a field value containing `${...}` that fails the `_ENV_REF_RE` pattern: missing `}`, invalid variable characters, wrong default separator (`-` instead of `:-`), or an empty name.","commonSituations":"Hand-editing config and typing `${VAR-default}` or forgetting the closing brace; intentionally wanting a literal `${` in a value (e.g. shell snippet in an arg) which the validator refuses; regex/JSON snippets pasted from docs that use `${}` placeholder syntax.","solutions":["Correct the reference to `${VAR}` or `${VAR:-default}` syntax (note the `:-`, not a single `-`).","Close the `${` with a matching `}` and use only letters, digits, and underscores in the variable name.","If a literal `${` is required, it is not supported — restructure the value (e.g. split via `args`) or set the value through env so it resolves before this check (a resolved value containing `${` is not rescanned)."],"exampleFix":"// before\n{\"args\": [\"--x=${FOO-BAR}\"]}  # single dash: malformed\n// after\n{\"args\": [\"--x=${FOO:-BAR}\"]}","handlingStrategy":"validation","validationCode":"import re\nREF = re.compile(r\"\\$\\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^{}]*))?\\}\")\ndef malformed_refs(value: str) -> list[str]:\n    spans = [m.span() for m in REF.finditer(value)]\n    return [value[m.start():] for m in re.finditer(r\"\\$\\{\", value)\n            if not any(s <= m.start() < e for s, e in spans)]","typeGuard":null,"tryCatchPattern":"try:\n    resolved = resolve_mcp_server_env(server_name, server_config)\nexcept RuntimeError as exc:\n    if \"malformed\" in str(exc):\n        field = str(exc).split(\" contains\")[0]\n        raise SystemExit(f\"Fix the ${{...}} syntax in {field}\") from exc\n    raise","preventionTips":["Always close `${` with `}` and use only `[A-Za-z0-9_]` in the variable name","Use `:-` (colon plus dash) for defaults — a single `-` is rejected","A literal `${` in a config value is not supported; escape the need by passing such values via env or args set elsewhere"],"tags":["mcp","config-validation","syntax"],"backgroundTag":"malformed-env-reference-syntax","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}