sgl-project/sglang · error · ValueError

file URI host must be local, got {parsed.netloc!r}

Error message

file URI host must be local, got {parsed.netloc!r}

What it means

A file:// material URI carried a non-local host component (netloc other than '' or 'localhost'). Only local files are supported for the file scheme.

Source

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

    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)
        return output_path
    if not scheme:
        output_path = _checked_material_file(
            Path(uri).expanduser(),
            label="MiniMax H3 material source",
        )
        _validate_material_once(batch, uri, output_path, condition_type=condition_type)
        return output_path
    if scheme == "s3":
        raise NotImplementedError(
            "MiniMax H3 s3:// material URIs require a configured artifact resolver"
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Use a plain absolute path '/path/to.png' or 'file:///path/to.png'
2. For remote assets use http(s):// and host the file
3. Mount the remote filesystem locally, then use the mount path

Example fix

# before
uri = "file://nas.example.com/data/img.png"
# after
uri = "/mnt/nas/data/img.png"

from urllib.parse import urlsplit
if uri.startswith('file://'):
    assert urlsplit(uri).netloc in ('', 'localhost')

except ValueError as e: rewrite URI to local path and retry

When it happens

Trigger: Passing 'file://hostname/path/to.png' or 'file://bucket/path' as the material URI.

Common situations: Developers assuming file:// supports remote hosts like smb://; copy-pasting URIs from other tooling that encodes the host.

Related errors

• tar material offset_data and size must be non-negative
• material URI has an invalid base64 payload
• material URI has invalid base64 padding
• material URI has data after base64 padding
• tar material payload is empty

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