sgl-project/sglang · error · ValueError

condition URI must be a non-empty string

Error message

condition URI must be a non-empty string

What it means

minimax_h3_localize_material_uri requires the URI to be a non-empty str; None, non-string, or '' was passed as the condition material.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py:777

def minimax_h3_localize_material_uri(
    batch: Any,
    uri: str,
    *,
    condition_type: str,
    condition_index: int,
    timeout_s: float = 120.0,
) -> str:
    """Return a local path for a canonical condition URI.

    Local paths and local ``file://`` URIs are validated and returned without
    copying. HTTP(S), base64/data and direct tar-member URIs are materialized
    once per request and cached for all MiniMax H3 consumers.
    """

    if not isinstance(uri, str) or not uri:
        raise ValueError("condition URI must be a non-empty string")
    parsed = None
    for special_scheme in ("data", "base64", "tar+offset", "tar+b64header"):
        if uri.startswith(special_scheme + ":"):
            scheme = special_scheme
            break
    else:
        parsed = urllib.parse.urlsplit(uri)
        scheme = parsed.scheme

    if scheme == "file":
        assert parsed is not None
        if parsed.netloc not in {"", "localhost"}:
            raise ValueError(f"file URI host must be local, got {parsed.netloc!r}")
        output_path = _checked_material_file(
            Path(urllib.parse.unquote(parsed.path)),
            label="MiniMax H3 material source",
        )
        _validate_material_once(batch, uri, output_path, condition_type=condition_type)

View on GitHub (pinned to 0132848349)

Solutions

1. Guard at the request boundary: skip the condition when uri is falsy
2. Fix the client payload to always include the URI for enabled conditions
3. Add schema validation requiring URI when the condition type is set

Example fix

# before
path = minimax_h3_localize_material_uri(batch, uri=req.image_uri, ...)
# after
if not req.image_uri:
    raise ValueError("image condition requires image_uri")
path = minimax_h3_localize_material_uri(batch, uri=req.image_uri, ...)

assert isinstance(uri, str) and uri, 'material URI required'

def is_valid_uri(uri) -> bool:
    return isinstance(uri, str) and len(uri) > 0

except ValueError as e: reject request with missing-media error

When it happens

Trigger: Passing None or '' as the URI for a keyframe/reference-video/reference-image condition, or an upstream stage dropping the field.

Common situations: Request JSON omitting the media field (parsed to None), default-None model fields passed straight through, prompt template leaving the URI blank.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• tar material offset_data and size must be non-negative
• material URI has data after base64 padding
• MiniMax-H3 adaln_t_table must have shape [N, D] with N >= 2,
• MiniMax H3 AdaLN cache has invalid timestep plans
• TP size must be positive.

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