sgl-project/sglang · error · ValueError

Invalid allowed media domain {domain!r}

Error message

Invalid allowed media domain {domain!r}

What it means

IDNA encoding of the allowed-media-domains entry failed with UnicodeError. Hostnames must be convertible to their ASCII IDNA form; entries with invalid IDNA characters (underscores, bare unicode that IDNA 2003/2008 rejects, stray punctuation) cannot be normalized and are rejected.

Source

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

        raise ValueError(
            f"Invalid allowed media domain {domain!r}: provide a hostname only"
        )

    # Brackets are URL syntax, not part of an IPv6 hostname.
    if domain.startswith("[") and domain.endswith("]"):
        domain = domain[1:-1]
    try:
        return str(ipaddress.ip_address(domain))
    except ValueError:
        if ":" in domain:
            raise ValueError(
                f"Invalid allowed media domain {domain!r}: ports are not supported"
            )

    try:
        normalized = domain.encode("idna").decode("ascii").lower()
    except UnicodeError as e:
        raise ValueError(f"Invalid allowed media domain {domain!r}") from e
    if not normalized:
        raise ValueError("allowed media domains cannot be empty")
    return normalized


def configure_media_url_security(
    allowed_media_domains: Optional[Sequence[str]] = None,
    max_file_size_mb: int = _DEFAULT_MEDIA_URL_MAX_FILE_SIZE_MB,
) -> list[str]:
    """Configure process-wide safeguards for client-supplied media URLs.

    A serving worker hosts one engine configuration, while media loading fans
    out to worker threads. Keeping the immutable policy here makes the same
    checks apply to image, video, audio, cache, and model-specific loaders.
    """

    if max_file_size_mb < 0:
        raise ValueError("media_url_max_file_size_mb must be non-negative")

View on GitHub (pinned to 0132848349)

Solutions

1. Remove invalid characters (replace '_' with '-'; wildcards are not supported at all)
2. Use the punycode/ASCII form of the hostname directly
3. Verify with python -c "print('host'.encode('idna'))" before adding

Example fix

# before
configure_media_url_security(allowed_media_domains=['my_bucket.cdn.example.com', '*.example.com'])
# after
configure_media_url_security(allowed_media_domains=['my-bucket.cdn.example.com', 'example.com'])

def idna_ok(host: str) -> bool:
    try: return bool(host.encode('idna').decode('ascii').lower())
    except UnicodeError: return False
domains = [d for d in domains if idna_ok(d)]

def is_idna_hostname(v: str) -> bool:
    import re
    return isinstance(v, str) and bool(re.fullmatch(r'(?!-)[A-Za-z0-9-]{1,63}(\.(?!-)[A-Za-z0-9-]{1,63})*', v))

When it happens

Trigger: Passing a hostname containing characters like '_', '*', or unicode that domain.encode('idna') rejects, e.g. 'my_bucket.cdn.example.com' or 'exämple.invalid-'.

Common situations: Allowlisting internal hostnames with underscores (common in some corporate DNS but invalid per RFC/IDNA); wildcard attempts like '*.example.com'; copy-paste of unicode hostnames.

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
• media_url_max_file_size_mb must be non-negative

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