encode/httpx · error · InvalidURL

URL component '{key}' too long

Error message

URL component '{key}' too long

What it means

Per-component length cap: each individual URL component passed as a kwarg to httpx.URL/urlparse (scheme, host, path, query, etc.) must not exceed MAX_URL_LENGTH (65536 chars). Distinct from the whole-URL check; applied during the kwargs validation loop.

Source

Thrown at httpx/_urlparse.py:269

    if "raw_path" in kwargs:
        raw_path = kwargs.pop("raw_path") or ""
        kwargs["path"], seperator, kwargs["query"] = raw_path.partition("?")
        if not seperator:
            kwargs["query"] = None

    # Ensure that IPv6 "host" addresses are always escaped with "[...]".
    if "host" in kwargs:
        host = kwargs.get("host") or ""
        if ":" in host and not (host.startswith("[") and host.endswith("]")):
            kwargs["host"] = f"[{host}]"

    # If any keyword arguments are provided, ensure they are valid.
    # -------------------------------------------------------------

    for key, value in kwargs.items():
        if value is not None:
            if len(value) > MAX_URL_LENGTH:
                raise InvalidURL(f"URL component '{key}' too long")

            # If a component includes any ASCII control characters including \t, \r, \n,
            # then treat it as invalid.
            if any(char.isascii() and not char.isprintable() for char in value):
                char = next(
                    char for char in value if char.isascii() and not char.isprintable()
                )
                idx = value.find(char)
                error = (
                    f"Invalid non-printable ASCII character in URL {key} component, "
                    f"{char!r} at position {idx}."
                )
                raise InvalidURL(error)

            # Ensure that keyword arguments match as a valid regex.
            if not COMPONENT_REGEX[key].fullmatch(value):
                raise InvalidURL(f"Invalid URL component '{key}'")

View on GitHub (pinned to b5addb64f0)

Solutions

1. Move oversized data to the request body (POST/PUT json=... or data=...).
2. Shorten or paginate the offending component before constructing the URL.
3. Validate component length before construction: assert len(value) <= 65536.
4. Compress large query values when GET semantics are mandatory.

Example fix

// before
url = httpx.URL("https://api.example.com/search", query="q=" + "a"*100000)  # InvalidURL

// after
client.post("https://api.example.com/search", json={"q": "a" * 100000})

from httpx._urlparse import MAX_URL_LENGTH

def safe_component(key: str, value: str) -> str:
    if len(value) > MAX_URL_LENGTH:
        raise ValueError(f"Component {key!r} too long ({len(value)} chars)")
    return value

url = httpx.URL("https://example.com", query=safe_component("query", q))

def component_ok(value: str, limit: int = 65536) -> bool:
    return len(value) <= limit

from httpx import InvalidURL

try:
    url = httpx.URL(base, query=huge_query)
except InvalidURL as e:
    if "too long" in str(e):
        client.post(base, json={"q": huge_query})
    else:
        raise

When it happens

Trigger: httpx.URL(path='/' + 'a'*100000), httpx.URL(query='x=' + 'y'*200000), or building URLs by passing a giant component via kwargs rather than the url string.

Common situations: Passing a huge base64 blob as the 'query' kwarg; building a path component from an unbounded list; migrating a long query string into the kwargs API.

Related errors

• URL too long
• Invalid non-printable ASCII character in URL, {char!r} at po
• Invalid non-printable ASCII character in URL {key} component
• Invalid URL component '{key}'
• Invalid IPv4 address: {host!r}

AI-assisted analysis of encode/httpx@b5addb64f0 (2026-08-04). Data as JSON: /data/errors/fca5befc335cc48f.json. Report an issue: GitHub.