{"record":{"id":"5ec856b1fce088cd","repo":"sgl-project/sglang","slug":"failed-to-load-real-esrgan-checkpoint-from-resol","errorCode":null,"errorMessage":"Failed to load Real-ESRGAN checkpoint from '{resolved_path}'. The file may be corrupted or not a valid PyTorch checkpoint. Original error: {e}","messagePattern":"Failed to load Real-ESRGAN checkpoint from '(.+?)'\\. The file may be corrupted or not a valid PyTorch checkpoint\\. Original error: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/postprocess/realesrgan_upscaler.py","lineNumber":592,"sourceCode":"        self._half_precision = half_precision\n\n    def _ensure_model_loaded(self) -> UpscalerModel:\n        \"\"\"Download/load Real-ESRGAN weights, detect arch, and cache globally.\"\"\"\n        model_path = self._model_path or _default_model_path_for_scale(self._scale)\n\n        # Resolve: local .pth pass-through, or HF repo → download single file\n        resolved_path = _resolve_model_path(model_path)\n\n        if resolved_path in _MODEL_CACHE:\n            return _MODEL_CACHE[resolved_path]\n\n        logger.info(\"Loading Real-ESRGAN weights from %s\", resolved_path)\n        try:\n            state_dict = torch.load(\n                resolved_path, map_location=\"cpu\", weights_only=True\n            )\n        except Exception as e:\n            raise RuntimeError(\n                f\"Failed to load Real-ESRGAN checkpoint from '{resolved_path}'. \"\n                f\"The file may be corrupted or not a valid PyTorch checkpoint. \"\n                f\"Original error: {e}\"\n            ) from e\n\n        # Some checkpoints wrap weights under a 'params' or 'params_ema' key\n        if \"params_ema\" in state_dict:\n            state_dict = state_dict[\"params_ema\"]\n        elif \"params\" in state_dict:\n            state_dict = state_dict[\"params\"]\n\n        try:\n            net = _build_net_from_state_dict(state_dict)\n            net.load_state_dict(state_dict, strict=True)\n        except (RuntimeError, KeyError) as e:\n            raise RuntimeError(\n                f\"Real-ESRGAN weight file '{resolved_path}' is not compatible \"\n                f\"with the supported architectures (SRVGGNetCompact / RRDBNet). \"","sourceCodeStart":574,"sourceCodeEnd":610,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/postprocess/realesrgan_upscaler.py#L574-L610","documentation":"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).","triggerScenarios":"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.","commonSituations":"Interrupted HF download leaving a partial file; old pickle-based ESRGAN checkpoints containing non-tensor objects; picking a safetensors file with a .pth name.","solutions":["Re-download the checkpoint (delete the HF cache dir for that repo)","Use a standard Real-ESRGAN .pth checkpoint compatible with weights_only=True","Verify the file opens with torch.load(..., map_location='cpu') standalone"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"import torch\ntorch.load(path, map_location=\"cpu\", weights_only=True)  # smoke-test before use","typeGuard":null,"tryCatchPattern":"try:\n    upscaler.upscale(img)\nexcept RuntimeError as e:\n    if \"Failed to load Real-ESRGAN checkpoint\" in str(e):\n        # clear cache and retry once with a fresh download\n        ...\n    raise","preventionTips":["Verify checkpoint integrity after download (file size/checksum)","Pre-download checkpoints in Docker build steps to avoid partial downloads at runtime"],"tags":["realesrgan","checkpoint","torch-load","postprocess"],"backgroundTag":"corrupted-checkpoint","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}