sgl-project/sglang · error · RuntimeError

Failed to load Real-ESRGAN checkpoint from '{resolved_path}'

Error message

Failed to load Real-ESRGAN checkpoint from '{resolved_path}'. The file may be corrupted or not a valid PyTorch checkpoint. Original error: {e}

What it means

RuntimeError raised by RealESRGANUpscaler._ensure_model_loaded when torch.load of the checkpoint .pth file throws — the file exists but cannot be parsed as a PyTorch checkpoint (corrupted download, wrong format, or weights_only incompatibility).

Source

Thrown at python/sglang/multimodal_gen/runtime/postprocess/realesrgan_upscaler.py:592

        self._half_precision = half_precision

    def _ensure_model_loaded(self) -> UpscalerModel:
        """Download/load Real-ESRGAN weights, detect arch, and cache globally."""
        model_path = self._model_path or _default_model_path_for_scale(self._scale)

        # Resolve: local .pth pass-through, or HF repo → download single file
        resolved_path = _resolve_model_path(model_path)

        if resolved_path in _MODEL_CACHE:
            return _MODEL_CACHE[resolved_path]

        logger.info("Loading Real-ESRGAN weights from %s", resolved_path)
        try:
            state_dict = torch.load(
                resolved_path, map_location="cpu", weights_only=True
            )
        except Exception as e:
            raise RuntimeError(
                f"Failed to load Real-ESRGAN checkpoint from '{resolved_path}'. "
                f"The file may be corrupted or not a valid PyTorch checkpoint. "
                f"Original error: {e}"
            ) from e

        # Some checkpoints wrap weights under a 'params' or 'params_ema' key
        if "params_ema" in state_dict:
            state_dict = state_dict["params_ema"]
        elif "params" in state_dict:
            state_dict = state_dict["params"]

        try:
            net = _build_net_from_state_dict(state_dict)
            net.load_state_dict(state_dict, strict=True)
        except (RuntimeError, KeyError) as e:
            raise RuntimeError(
                f"Real-ESRGAN weight file '{resolved_path}' is not compatible "
                f"with the supported architectures (SRVGGNetCompact / RRDBNet). "

View on GitHub (pinned to 0132848349)

Solutions

1. Re-download the checkpoint (delete the HF cache dir for that repo)
2. Use a standard Real-ESRGAN .pth checkpoint compatible with weights_only=True
3. Verify the file opens with torch.load(..., map_location='cpu') standalone

import torch
torch.load(path, map_location="cpu", weights_only=True)  # smoke-test before use

try:
    upscaler.upscale(img)
except RuntimeError as e:
    if "Failed to load Real-ESRGAN checkpoint" in str(e):
        # clear cache and retry once with a fresh download
        ...
    raise

When it happens

Trigger: Upscale/upscale_batched triggering lazy model load where the .pth is truncated, is a pickled legacy file blocked by weights_only=True, or is actually a zip/safetensors/ONNX file.

Common situations: Interrupted HF download leaving a partial file; old pickle-based ESRGAN checkpoints containing non-tensor objects; picking a safetensors file with a .pth name.

Related errors

• Unsupported RRDBNet conv_first input channels: {in_channels}
• Real-ESRGAN weight file '{resolved_path}' is not compatible
• Unsupported activation type: {act_type}
• All frames in a batch must have the same resolution
• RealESRGAN batch upscale did not produce all frames

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