sgl-project/sglang · error · ValueError

Remote media exceeds the {max_bytes} byte download limit

Error message

Remote media exceeds the {max_bytes} byte download limit

What it means

During download, the server's Content-Length header declares a size larger than the configured max_bytes limit, so download_remote_media aborts before reading the body. This is the first line of the byte-limit enforcement, protecting worker memory from oversized media.

Source

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

            location = response.headers.get("Location")
            if response.status_code in _MEDIA_URL_REDIRECT_STATUS_CODES and location:
                if redirect_count == _MAX_MEDIA_URL_REDIRECTS:
                    raise requests.exceptions.TooManyRedirects(
                        f"Media URL exceeded {_MAX_MEDIA_URL_REDIRECTS} redirects: {url}"
                    )
                current_url = urljoin(response.url, location)
                continue

            response.raise_for_status()
            max_bytes = _media_url_max_file_size_bytes
            content_length = response.headers.get("Content-Length")
            if max_bytes and content_length is not None:
                try:
                    declared_size = int(content_length)
                except ValueError:
                    declared_size = None
                if declared_size is not None and declared_size > max_bytes:
                    raise ValueError(
                        f"Remote media exceeds the {max_bytes} byte download limit"
                    )

            content = bytearray()
            for chunk in response.iter_content(chunk_size=64 * 1024):
                if not chunk:
                    continue
                if time.monotonic() > deadline:
                    raise requests.exceptions.Timeout(
                        f"Timed out while downloading media URL: {url}"
                    )
                if max_bytes and len(content) + len(chunk) > max_bytes:
                    raise ValueError(
                        f"Remote media exceeds the {max_bytes} byte download limit"
                    )
                content.extend(chunk)
            return bytes(content)

View on GitHub (pinned to 0132848349)

Solutions

1. Raise --media-url-max-file-size-mb (or configure_media_url_security(max_file_size_mb=...)) to fit the real asset size
2. Compress/downsample the media before hosting it
3. Reject oversized requests client-side with a clear message

Example fix

# before
python -m sglang.launch_server  # default cap, 2GB video fails
# after
python -m sglang.launch_server --media-url-max-file-size-mb 8192

# client-side: HEAD the asset and compare against the configured cap
import requests
size = int(requests.head(url, timeout=10).headers.get('Content-Length', 0))
if size > MAX_BYTES: raise ClientError('media too large; compress or raise the cap')

try:
    data = download_remote_media(url, timeout=30)
except ValueError as e:
    if 'download limit' in str(e):
        return HTTPException(413, 'remote media exceeds configured size limit')
    raise

When it happens

Trigger: Fetching a video/image whose Content-Length exceeds the max-file-size policy (default _DEFAULT_MEDIA_URL_MAX_FILE_SIZE_MB); a server liesing with a huge Content-Length also triggers it.

Common situations: Large video files exceeding the default media size cap; client uploads referencing multi-GB files; hostile servers trying to exhaust memory.

Related errors

• allowed media domains must be strings
• allowed media domains cannot be empty
• Invalid allowed media domain {domain!r}: provide a hostname
• Invalid allowed media domain {domain!r}: ports are not suppo
• Invalid allowed media domain {domain!r}

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