Load HunyuanImage 3.0 Model:
HunyuanImage3ModelLoader, displayed in ComfyUI as “Load HunyuanImage 3.0 Model,” prepares a HunyuanImage 3.0 checkpoint for use in an image-generation workflow. A checkpoint contains the learned weights that define a model’s capabilities. This node supports the Instruct-Distil, Instruct, and Base variants and automatically identifies the variant by examining those weights, rather than requiring you to select a model type manually. Its purpose is to make loading these models straightforward while handling their integration with ComfyUI’s model system. The node is described as supporting any HunyuanImage 3.0 checkpoint format, but the checkpoint should be prepared for ComfyUI and compatible with the installed extension. It loads the image-generation model; it does not generate an image or configure an entire workflow by itself.
Load HunyuanImage 3.0 Model Input Parameters:
model
A required COMBO selection that chooses the HunyuanImage 3.0 checkpoint to load. The available options come from ComfyUI’s registered diffusion_models file list, normally populated by files in ComfyUI/models/diffusion_models and any additional configured locations for that category. Choose a checkpoint converted for ComfyUI; the loader determines whether it is Instruct-Distil, Instruct, or Base from its weights. This selection determines which model is prepared for your workflow, so changing it changes the underlying model used by subsequent generation steps. When executed, the node resolves the selected filename to a full file path and loads that checkpoint. Options are installation-dependent rather than a fixed list. The default is selected by _default_checkpoint(); its implementation is not provided, so a specific default filename cannot be established from the supplied code. Minimum and maximum values do not apply because this is a file-selection dropdown, not a numeric setting.
Load HunyuanImage 3.0 Model Output Parameters:
model
A MODEL connection containing the loaded HunyuanImage 3.0 model wrapped for use within ComfyUI’s model-management system. The node returns the model patcher produced by the HunyuanImage 3.0 loading routine, which allows compatible downstream nodes to work with the loaded model. For your workflow, this is the prepared image-generation model that subsequent processing or sampling stages can use. It is not an image, a text prompt, or a report of the detected variant, and there is no separate output identifying whether the checkpoint is Instruct-Distil, Instruct, or Base. Connect it to an appropriate MODEL input in a workflow designed for HunyuanImage 3.0.
Load HunyuanImage 3.0 Model Usage Tips:
- Place your ComfyUI-compatible HunyuanImage 3.0 checkpoint in
ComfyUI/models/diffusion_modelsor another configureddiffusion_modelslocation. Refresh the model list or restart ComfyUI if a newly added checkpoint does not appear. - Select the checkpoint you intend to use without looking for a separate Base, Instruct, or Instruct-Distil setting. Variant detection is automatic and based on the checkpoint’s weights; renaming a file does not change its model type.
- Start with an example workflow supplied for your checkpoint or the HunyuanImage 3.0 extension. This loader prepares only the model, so other required generation components must be provided elsewhere in the workflow.
- When switching between model variants, check the checkpoint’s recommended downstream generation settings. Automatic identification during loading does not mean this node sets every sampling or workflow option for you.
- This node exposes only checkpoint selection. It has no controls for precision, device placement, memory limits, sampling steps, or image resolution, so any supported adjustments to those settings must be made elsewhere.
- If memory is limited, close other GPU-intensive applications before loading. If your extension offers multiple compatible checkpoint formats, consult its documentation for their memory requirements rather than assuming every format has the same resource needs.
Load HunyuanImage 3.0 Model Common Errors and Solutions:
Checkpoint missing from the model dropdown
- Explanation: The dropdown lists files registered under ComfyUI’s
diffusion_modelscategory. A checkpoint stored elsewhere, added after the list was populated, or not recognized by ComfyUI’s file listing may be absent. This is a selection issue rather than a confirmed loader exception. - Solution: Confirm that the checkpoint is in
ComfyUI/models/diffusion_modelsor a correctly configured additional location. Check that the download is complete, then refresh the model list or restart ComfyUI.
Selected checkpoint cannot be found
- Explanation: Execution requires the selected filename to resolve to an existing file. If the file was moved, renamed, deleted, or stored on a disconnected drive, path resolution can fail. The supplied code uses
get_full_path_or_raise, but does not show the exact resulting error text. - Solution: Restore the file or select its current entry from the dropdown. If you use an external drive or network location, reconnect it and verify that ComfyUI can access the checkpoint.
Checkpoint is incompatible or model type cannot be detected
- Explanation: The loader expects HunyuanImage 3.0 weights and identifies the variant from their contents. A checkpoint for another model family, an incompatible conversion, or incomplete weights may prevent identification or loading. The supplied excerpts do not establish an exact error message for this case.
- Solution: Verify that you downloaded a HunyuanImage 3.0 checkpoint prepared for ComfyUI. Follow the extension’s checkpoint preparation instructions and confirm that your installed extension version supports that release.
Missing keys, unexpected keys, or tensor size mismatch
- Explanation: These are possible model-loading diagnostics when a checkpoint’s stored weights do not match the architecture expected by the installed loader. They may indicate an incompatible conversion, a different model architecture, or a version mismatch. Not every warning about keys is necessarily fatal; the surrounding log determines whether loading failed.
- Solution: Check that the checkpoint and extension versions are compatible. Update the extension if required by the checkpoint documentation, use a documented conversion, and review the first relevant error in the ComfyUI console rather than only the final failure notice.
Checkpoint cannot be read or deserialized
- Explanation: Loading may fail if the downloaded file is incomplete, damaged, unreadable, or not actually a supported checkpoint file. Exact file-reading errors depend on the underlying loader and are not included in the supplied source.
- Solution: Compare the file size or checksum with the download source when available. Download the checkpoint again if necessary, confirm that the file is fully downloaded rather than a placeholder, and check that the account running ComfyUI has read access.
Out of memory during loading
- Explanation: Preparing a large model can exceed available system RAM or GPU memory, depending on the checkpoint and ComfyUI’s loading behavior. A message such as “CUDA out of memory” is a possible runtime error, not a custom message shown in this node’s source.
- Solution: Close other memory-intensive applications and unload unused models before trying again. Check the checkpoint’s hardware requirements and the extension’s documented memory-saving options. This node has no memory or precision controls, so any supported changes must be configured elsewhere.
