Comfy-Org/ComfyUI · error · Exception

Upscale model must be a single-image model.

Error message

Upscale model must be a single-image model.

What it means

The upscale model loader loads a state dict via ModelLoader().load_from_state_dict and requires the result to be an ImageModelDescriptor — i.e. a single-image super-resolution architecture (ESRGAN/RealESRGAN/SwinIR family). Video or otherwise unsupported upscale checkpoints produce a different descriptor type and are rejected.

Source

Thrown at comfy_extras/nodes_upscale_model.py:44

            category="model/loaders",
            inputs=[
                io.Combo.Input("model_name", options=folder_paths.get_filename_list("upscale_models")),
            ],
            outputs=[
                io.UpscaleModel.Output(),
            ],
        )

    @classmethod
    def execute(cls, model_name) -> io.NodeOutput:
        model_path = folder_paths.get_full_path_or_raise("upscale_models", model_name)
        sd = comfy.utils.load_torch_file(model_path, safe_load=True)
        if "module.layers.0.residual_group.blocks.0.norm1.weight" in sd:
            sd = comfy.utils.state_dict_prefix_replace(sd, {"module.":""})
        out = ModelLoader().load_from_state_dict(sd).eval()

        if not isinstance(out, ImageModelDescriptor):
            raise Exception("Upscale model must be a single-image model.")

        out.patcher = comfy.model_patcher.CoreModelPatcher(out.model, load_device=model_management.get_torch_device(), offload_device=model_management.unet_offload_device())
        return io.NodeOutput(out)

    load_model = execute  # TODO: remove


class ImageUpscaleWithModel(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ImageUpscaleWithModel",
            display_name="Upscale Image (using Model)",
            category="image/upscaling",
            search_aliases=["upscale", "upscaler", "upsc", "enlarge image", "super resolution", "hires", "superres", "increase resolution"],
            inputs=[
                io.UpscaleModel.Input("upscale_model"),
                io.Image.Input("image"),

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Use a genuine single-image upscale model (RealESRGAN, ESRGAN, 4x-UltraSharp, SwinIR, etc.)
2. Move video restoration models to the correct folder type and use the video-appropriate nodes
3. If the model should be supported, verify the state dict keys are not prefixed/stripped incorrectly (the node already strips 'module.' for SPAN-style models)

sd = comfy.utils.load_torch_file(path, safe_load=True)
# single-image upscale models carry 2d conv/upsample weights, not video (3d) ones
if any(k.endswith(".weight") and v.ndim == 5 for v in sd.values()):
    raise SystemExit(f"{path} looks like a video model; not usable here")

def is_single_image_upscale(sd: dict) -> bool:
    return not any(v.ndim == 5 for v in sd.values() if v.ndim > 0)

When it happens

Trigger: Loading a video super-resolution model (e.g. a RealBasicVSR/VideoSR checkpoint saved into models/upscale_models) or a non-upscale state dict; the loader's architecture detection does not map it to a single-image model class.

Common situations: Users drop VSR video models into the upscale_models folder expecting them to work with ImageUpscaleWithModel; mixed model folders; a renamed/repackaged checkpoint whose keys do not match any known single-image architecture.

Related errors

• INVALID_TAG_FILTER
• ERROR: audio encoder file is invalid or unsupported embed_di
• ERROR: audio encoder not supported.
• Control type {max_type_name}({max_type}) is out of range for
• CORRUPTED MODEL: one of the q-k-v values for the text encode

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/5fb6c87b4f5504a3. Report an issue: GitHub.