NousResearch/hermes-agent · error · RuntimeError

Malformed proxy environment variable {key}={value!r}. Fix or

Error message

Malformed proxy environment variable {key}={value!r}. Fix or unset your proxy settings and try again.

What it means

Pre-flight proxy validation: for each of HTTPS_PROXY/HTTP_PROXY/ALL_PROXY (and lowercase variants), urlparse(value).port raises ValueError for garbage such as 'http://127.0.0.1:6153export'. Hermes rejects malformed proxy values up front — with the offending variable named — instead of letting httpx fail later with an opaque error.

Source

Thrown at agent/auxiliary_client.py:3531

    which concatenates 'export' into the port number.  Without this
    check the OpenAI/httpx client raises a cryptic ``Invalid port``
    error that doesn't name the offending env var.
    """
    from urllib.parse import urlparse

    normalize_proxy_env_vars()

    for key in ("HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY",
                "https_proxy", "http_proxy", "all_proxy"):
        value = str(os.environ.get(key) or "").strip()
        if not value:
            continue
        try:
            parsed = urlparse(value)
            if parsed.scheme:
                _ = parsed.port          # raises ValueError for e.g. '6153export'
        except ValueError as exc:
            raise RuntimeError(
                f"Malformed proxy environment variable {key}={value!r}. "
                "Fix or unset your proxy settings and try again."
            ) from exc


def _validate_base_url(base_url: str) -> None:
    """Reject obviously broken custom endpoint URLs before they reach httpx."""
    from urllib.parse import urlparse

    candidate = str(base_url or "").strip()
    if not candidate or candidate.startswith("acp://"):
        return
    try:
        parsed = urlparse(candidate)
        if parsed.scheme in {"http", "https"}:
            _ = parsed.port              # raises ValueError for malformed ports
    except ValueError as exc:
        raise RuntimeError(

View on GitHub (pinned to c896c09c42)

Solutions

Fix the value to a valid URL form: export HTTPS_PROXY='http://127.0.0.1:6153'
Unset the broken variable if no proxy is actually needed
Audit shell rc files and CI environment definitions for the typo'd export
Verify the fix parses: python -c "from urllib.parse import urlparse; print(urlparse('http://127.0.0.1:6153').port)"

Example fix

# before
export HTTPS_PROXY=http://127.0.0.1:6153export

# after
export HTTPS_PROXY=http://127.0.0.1:6153

Defensive patterns

Strategy: validation

Validate before calling

import os
from urllib.parse import urlparse

def proxy_env_valid() -> str | None:
    for key in ("HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY",
                "https_proxy", "http_proxy", "all_proxy"):
        value = str(os.environ.get(key) or "").strip()
        if not value:
            continue
        try:
            parsed = urlparse(value)
            if parsed.scheme:
                _ = parsed.port
        except ValueError:
            return f"{key}={value!r}"
    return None

bad = proxy_env_valid()
if bad:
    raise SystemExit(f"Fix malformed proxy variable {bad} before starting")

Try / catch

try:
    build_auxiliary_client()
except RuntimeError as e:
    if "Malformed proxy environment variable" in str(e):
        unset_or_fix_proxy_from_message(str(e))  # message names the offending key/value
        build_auxiliary_client()
    else:
        raise

Prevention

Quote proxy exports in shell rc files: export HTTPS_PROXY='http://host:port'
Validate proxy env vars in CI pipeline preflight before jobs that make HTTP calls
After changing proxy tools, re-parse each proxy URL before launching long-running processes

When it happens

Trigger: Any of the six proxy env vars set to a value whose port component is unparseable (e.g. digits glued to 'export', scheme with no colon, or truncated host:port) before an auxiliary HTTP client is constructed.

Common situations: Shell quoting accident appending text to the port ('6153export'); CI injecting malformed proxy variables; proxy-switcher utilities writing bad values into the environment.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/61fe9233c899e0b5. Report an issue: GitHub.