FoundationAgents/MetaGPT · error · ValueError

'openai.proxy' must be specified as either a string URL or a

Error message

'openai.proxy' must be specified as either a string URL or a dict with string URL under the https and/or http keys.

What it means

This ValueError is raised by MetaGPT's vendored OpenAI-compatible HTTP layer (_requests_proxies_arg) when the proxy setting passed to a provider resolves to neither None, a string, nor a dict. The helper builds the 'proxies' argument for requests.request, so any other Python type (int, list, tuple, bool) is rejected immediately. It surfaces as an 'openai.proxy' error because the value normally originates from the proxy field of the LLM provider config.

Source

Thrown at metagpt/provider/general_api_base.py:180

def _build_api_url(url, query):
    scheme, netloc, path, base_query, fragment = urlsplit(url)

    if base_query:
        query = "%s&%s" % (base_query, query)

    return urlunsplit((scheme, netloc, path, query, fragment))


def _requests_proxies_arg(proxy) -> Optional[Dict[str, str]]:
    """Returns a value suitable for the 'proxies' argument to 'requests.request."""
    if proxy is None:
        return None
    elif isinstance(proxy, str):
        return {"http": proxy, "https": proxy}
    elif isinstance(proxy, dict):
        return proxy.copy()
    else:
        raise ValueError(
            "'openai.proxy' must be specified as either a string URL or a dict with string URL under the https and/or http keys."
        )


def _aiohttp_proxies_arg(proxy) -> Optional[str]:
    """Returns a value suitable for the 'proxies' argument to 'aiohttp.ClientSession.request."""
    if proxy is None:
        return None
    elif isinstance(proxy, str):
        return proxy
    elif isinstance(proxy, dict):
        return proxy["https"] if "https" in proxy else proxy["http"]
    else:
        raise ValueError(
            "'openai.proxy' must be specified as either a string URL or a dict with string URL under the https and/or http keys."
        )

View on GitHub (pinned to 11cdf466d0)

Solutions

1. Set the proxy as a single string URL, e.g. proxy: "http://127.0.0.1:7890" in config2.yaml.
2. Or set it as a dict with string URLs under http/https keys, e.g. proxy: {http: "http://127.0.0.1:7890", https: "http://127.0.0.1:7890"}.
3. If no proxy is intended, set proxy to null/omit it so the helper returns None instead of raising.
4. Check code that builds the provider Config programmatically and cast the value with str() before passing it.

Example fix

# before (config2.yaml)
llm:
  proxy: 7890          # int -> ValueError

# after
llm:
  proxy: "http://127.0.0.1:7890"

def is_valid_proxy(p) -> bool:
    return p is None or isinstance(p, str) or (
        isinstance(p, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in p.items())
    )

assert is_valid_proxy(config.llm.proxy), "proxy must be str URL or dict of str URLs"

from typing import Union, Optional, Dict

def is_proxy_config(p) -> TypeGuard[Union[str, Dict[str, str], None]]:
    if p is None or isinstance(p, str):
        return True
    return isinstance(p, dict) and all(isinstance(v, str) for v in p.values())

try:
    provider = OpenAIGPTAPI(config)
except ValueError as e:
    if "openai.proxy" in str(e):
        raise SystemExit(f"Fix proxy config: {e}") from e
    raise

When it happens

Trigger: Calling any provider built on metagpt/provider/general_api_base.py (OpenAI, Azure, self-hosted endpoints) with a proxy config value that is truthy but not a string or dict, e.g. proxy: 1, proxy: ["http://host:port"], or proxy: true in yaml; the sync requests path then formats proxies and hits the else-branch.

Common situations: YAML config typos (unquoted port numbers, a list instead of a single URL), environment variables parsed into non-string types, programmatic Config construction that passes os.environ values or integers, or copying a curl-style proxy list into config2.yaml.

Related errors

• please check MilvusConnection, uri must be set.
• Rollouts must be greater than 2 if there is no tree to load
• Headers must be a dictionary
• Missing fields: {missing_fields}
• use `review` after `fill`

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/6c50748fda607d71. Report an issue: GitHub.