sgl-project/sglang · error · FileNotFoundError

{label} does not exist or is not a file: {path}

Error message

{label} does not exist or is not a file: {path}

What it means

Raised by _checked_material_file when a localized material source path does not exist or is not a regular file (directory, broken symlink, fifo). The pipeline validates all material URIs resolve to real, readable files before downstream stages.

Source

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

        size,
        str(header.get("member") or "") or None,
    )


def _safe_suffix(value: str | None) -> str | None:
    if not value:
        return None
    suffix = Path(urllib.parse.urlsplit(value).path).suffix.lower()
    if suffix and len(suffix) <= 10 and suffix[1:].isalnum():
        return suffix
    return None


def _checked_material_file(path: Path, *, label: str) -> str:
    """Validate that a localized source exists and is non-empty."""

    if not path.is_file():
        raise FileNotFoundError(f"{label} does not exist or is not a file: {path}")
    if path.stat().st_size <= 0:
        raise ValueError(f"{label} is empty: {path}")
    return str(path)


def _parse_frame_rate(value: Any) -> float:
    if value in {None, "", "N/A", "0/0"}:
        return 0.0
    raw = str(value)
    try:
        if "/" in raw:
            numerator, denominator = raw.split("/", 1)
            denominator_value = float(denominator)
            parsed = float(numerator) / denominator_value if denominator_value else 0.0
        else:
            parsed = float(raw)
        return parsed if math.isfinite(parsed) else 0.0
    except (TypeError, ValueError, ZeroDivisionError):

View on GitHub (pinned to 0132848349)

Solutions

1. Check the path exists and is a file: ls -l /path/to/material
2. Fix the URI/path in the request or mount the material volume at the expected location
3. Ensure material download/extraction completes before the pipeline stage runs

Example fix

// before
uri = "file:///data/missing.jpg"
// after
uri = "file:///data/materials/missing.jpg"  # verified with Path(uri).is_file()

from pathlib import Path
p = Path(local_path)
assert p.is_file(), f"material missing: {p}"

def is_material_file(p: str) -> bool:
    from pathlib import Path
    return Path(p).expanduser().is_file()

try:
    minimax_h3_localize_material_uri(uri)
except FileNotFoundError as e:
    retry_after_sync(uri)  # re-check after download/mount settles

When it happens

Trigger: Calling minimax_h3_localize_material_uri with a file:// or plain path URI where the path is missing, is a directory, or points through a broken symlink.

Common situations: Material directory mounted at a different path in a container, typo'd path in the request, symlink target absent, or material file not yet synced/downloaded when the pipeline runs.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• MiniMax H3 AdaLN cache does not exist: {self.path}
• tar material source does not exist or is not a file: {source
• metal shader source not found: {metal_src}
• fl2va requires first_frame, last_frame, or both
• ref2va requires at least one of reference_image, reference_v

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