{"record":{"id":"5fb6c87b4f5504a3","repo":"Comfy-Org/ComfyUI","slug":"upscale-model-must-be-a-single-image-model","errorCode":null,"errorMessage":"Upscale model must be a single-image model.","messagePattern":"Upscale model must be a single-image model\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_upscale_model.py","lineNumber":44,"sourceCode":"            category=\"model/loaders\",\n            inputs=[\n                io.Combo.Input(\"model_name\", options=folder_paths.get_filename_list(\"upscale_models\")),\n            ],\n            outputs=[\n                io.UpscaleModel.Output(),\n            ],\n        )\n\n    @classmethod\n    def execute(cls, model_name) -> io.NodeOutput:\n        model_path = folder_paths.get_full_path_or_raise(\"upscale_models\", model_name)\n        sd = comfy.utils.load_torch_file(model_path, safe_load=True)\n        if \"module.layers.0.residual_group.blocks.0.norm1.weight\" in sd:\n            sd = comfy.utils.state_dict_prefix_replace(sd, {\"module.\":\"\"})\n        out = ModelLoader().load_from_state_dict(sd).eval()\n\n        if not isinstance(out, ImageModelDescriptor):\n            raise Exception(\"Upscale model must be a single-image model.\")\n\n        out.patcher = comfy.model_patcher.CoreModelPatcher(out.model, load_device=model_management.get_torch_device(), offload_device=model_management.unet_offload_device())\n        return io.NodeOutput(out)\n\n    load_model = execute  # TODO: remove\n\n\nclass ImageUpscaleWithModel(io.ComfyNode):\n    @classmethod\n    def define_schema(cls):\n        return io.Schema(\n            node_id=\"ImageUpscaleWithModel\",\n            display_name=\"Upscale Image (using Model)\",\n            category=\"image/upscaling\",\n            search_aliases=[\"upscale\", \"upscaler\", \"upsc\", \"enlarge image\", \"super resolution\", \"hires\", \"superres\", \"increase resolution\"],\n            inputs=[\n                io.UpscaleModel.Input(\"upscale_model\"),\n                io.Image.Input(\"image\"),","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_upscale_model.py#L26-L62","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a genuine single-image upscale model (RealESRGAN, ESRGAN, 4x-UltraSharp, SwinIR, etc.)","Move video restoration models to the correct folder type and use the video-appropriate nodes","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)"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"sd = comfy.utils.load_torch_file(path, safe_load=True)\n# single-image upscale models carry 2d conv/upsample weights, not video (3d) ones\nif any(k.endswith(\".weight\") and v.ndim == 5 for v in sd.values()):\n    raise SystemExit(f\"{path} looks like a video model; not usable here\")","typeGuard":"def is_single_image_upscale(sd: dict) -> bool:\n    return not any(v.ndim == 5 for v in sd.values() if v.ndim > 0)","tryCatchPattern":null,"preventionTips":["Keep models/upscale_models reserved for single-image SR architectures","Sanity-check unknown checkpoints by listing top-level key prefixes first"],"tags":["upscale","model-loading","super-resolution"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}