sgl-project/sglang · error · RuntimeError

Real-ESRGAN weight file '{resolved_path}' is not compatible

Error message

Real-ESRGAN weight file '{resolved_path}' is not compatible with the supported architectures (SRVGGNetCompact / RRDBNet). Please ensure you are using a valid Real-ESRGAN checkpoint. Original error: {e}

What it means

RuntimeError raised when the loaded state_dict cannot be built into or loaded into SRVGGNetCompact/RRDBNet — _build_net_from_state_dict or strict load_state_dict raised RuntimeError/KeyError. The file is a valid torch checkpoint but not a supported Real-ESRGAN architecture.

Source

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

            )
        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). "
                f"Please ensure you are using a valid Real-ESRGAN checkpoint. "
                f"Original error: {e}"
            ) from e
        net.eval()

        device = current_platform.get_local_torch_device()
        if self._half_precision:
            net = net.half()
        net = net.to(device)

        # Detect the model's native scale from network architecture
        native_scale = 4  # sensible default
        if hasattr(net, "upscale"):
            native_scale = net.upscale
        elif hasattr(net, "scale"):
            native_scale = net.scale

View on GitHub (pinned to 0132848349)

Solutions

1. Use a checkpoint for the supported architectures (SRVGGNetCompact 'realesr-animevideo' or RRDBNet 'x4plus/x2plus')
2. Check the state_dict keys with torch.load and compare against expected layout
3. Provide the exact file via 'repo_id:filename' syntax

sd = torch.load(pth, map_location="cpu", weights_only=True)
assert any(k.startswith("body.") for k in sd) or k in sd for k in (), ""

try:
    upscaler.upscale(img)
except RuntimeError as e:
    if "not compatible" in str(e):
        raise ValueError(f"bad checkpoint: {e}") from e
    raise

When it happens

Trigger: Loading weights for RealESRGAN-anime, a custom RRDB variant with different num_block/num_feat, or a non-Real-ESRGAN super-resolution model; strict=True load failing on extra/missing keys.

Common situations: Wrong checkpoint variant chosen for the model class; partially exported state_dicts; checkpoints from newer Real-ESRGAN versions with extra keys.

Related errors

• Unsupported RRDBNet conv_first input channels: {in_channels}
• Failed to load Real-ESRGAN checkpoint from '{resolved_path}'
• 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/5cb5ead3c4f8a63f. Report an issue: GitHub.