sgl-project/sglang · error · ValueError

media URL timeout must be positive

Error message

media URL timeout must be positive

What it means

download_remote_media requires a strictly positive timeout (seconds) that bounds the whole download including redirects. Zero or negative timeouts are rejected because the deadline-based loop (time.monotonic() + timeout) would immediately expire and the semantics would be undefined.

Source

Thrown at python/sglang/srt/utils/common.py:1599

    if _allowed_media_domains and hostname not in _allowed_media_domains:
        raise ValueError(
            "Media URL domain is not allowed. "
            f"Allowed domains: {sorted(_allowed_media_domains)}; "
            f"input domain: {hostname}"
        )


def download_remote_media(url: str, timeout: float) -> bytes:
    """Download one HTTP(S) media object under the configured URL policy.

    Redirects are followed manually so every destination is validated before
    a connection is made. The response is streamed to enforce both the total
    request deadline and the configured byte limit without first buffering an
    attacker-controlled body in memory.
    """

    if timeout <= 0:
        raise ValueError("media URL timeout must be positive")

    session = get_mm_http_session()
    deadline = time.monotonic() + timeout
    current_url = url

    for redirect_count in range(_MAX_MEDIA_URL_REDIRECTS + 1):
        # Validate the same normalized URL representation that requests sends
        # to urllib3. This avoids parser disagreements around backslashes and
        # userinfo separators.
        prepared_url = requests.Request("GET", current_url).prepare().url
        if prepared_url is None:
            raise ValueError(f"Invalid media URL: {current_url!r}")
        _assert_media_url_allowed(prepared_url)

        remaining = deadline - time.monotonic()
        if remaining <= 0:
            raise requests.exceptions.Timeout(
                f"Timed out while downloading media URL: {url}"

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a positive timeout such as 10 or 30 seconds
2. Default the value when unset: timeout = timeout or _DEFAULT_TIMEOUT
3. Clamp: timeout = max(1, timeout)

Example fix

# before
data = download_remote_media(url, timeout=0)
# after
data = download_remote_media(url, timeout=max(1, int(timeout or 10)))

timeout = timeout if isinstance(timeout, (int, float)) and timeout > 0 else 30
data = download_remote_media(url, timeout=timeout)

When it happens

Trigger: Calling download_remote_media(url, timeout=0) or with a negative value; often when a caller forwards a user/config-supplied timeout that defaults to 0 or was computed as (deadline - now) <= 0.

Common situations: Passing None-handling code that coerces to 0; copying a per-request timeout of 0 meaning 'no wait'; misconfigured SGLANG_MEDIA_URL_TIMEOUT-style config.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Failed to edit image: {str(e)}
• Failed to generate image: {str(e)}
• Network error after {consecutive_errors} consecutive failure
• invalid IPv6 address format: missing ']'
• invalid IPv6 address: {host}

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/54d0cef399d2ab1a. Report an issue: GitHub.