Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-HunyuanImage3 > HunyuanImage 3.0 Guidance

ComfyUI Node: HunyuanImage 3.0 Guidance

Class Name

HunyuanImage3Guidance

Category
conditioning/hunyuan image 3
Author
PedroMarinhoDev (Account age: 43days)
Extension
ComfyUI-HunyuanImage3
Latest Updated
2026-11-03
Github Stars
0.04K

How to Install ComfyUI-HunyuanImage3

Install this extension via the ComfyUI Manager by searching for ComfyUI-HunyuanImage3
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-HunyuanImage3 in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

HunyuanImage 3.0 Guidance Description

Adds model-specific guidance to conditioning for HunyuanImage 3.0 Instruct-Distil.

HunyuanImage 3.0 Guidance:

HunyuanImage3Guidance, displayed as “HunyuanImage 3.0 Guidance,” prepares conditioning for the HunyuanImage 3.0 Instruct-Distil checkpoint by attaching the guidance information that this model expects. Unlike conventional classifier-free guidance (CFG), which controls generation through the sampler, this guidance is supplied directly to the model and processed through a guidance embedding. The node converts your chosen guidance strength into the model’s expected internal units, allowing you to configure this model-specific setting without manually editing conditioning data. It is intended only for Instruct-Distil, not as a general-purpose guidance adjustment for other checkpoints. The checkpoint’s own guidance setting is 2.5, and the sampler’s CFG should remain at 1.0 when you use this approach.

HunyuanImage 3.0 Guidance Input Parameters:

conditioning

A required CONDITIONING connection containing the encoded information used to guide generation, typically prepared by a compatible text-encoding node. This node preserves each entry’s existing encoded content and copies its associated metadata before adding a guidance value. Other metadata is retained, but an existing metadata field named guidance is replaced with the newly selected value. If your conditioning contains several entries, the same guidance strength is attached to every entry. This parameter accepts structured conditioning rather than a plain-text prompt, image, or latent. There is no numeric minimum, maximum, or default value; you must supply a compatible CONDITIONING connection.

guidance_scale

A required FLOAT setting that specifies the guidance strength supplied directly to the Instruct-Distil model. Its minimum is 0.0, its maximum is 100.0, and its adjustment step is 0.01. The schema declares its default through DEFAULT_GUIDANCE_SCALE; the provided excerpt does not show that constant’s numeric definition, but the node description explicitly identifies 2.5 as the checkpoint’s own setting and recommended starting point. Internally, the node multiplies this setting by 1000 and stores the result as a single-element bfloat16 tensor in the conditioning metadata. For example, 2.5 becomes an internal value of 2500; you should enter 2.5, not 2500. This conversion matches the model’s expected timestep-related units and is not an additional artistic strength multiplier that you need to compensate for. Changing this setting changes the guidance information supplied to the model, but the provided code does not establish a guaranteed relationship between higher values and better prompt adherence, image quality, or detail. A value of 0.0 supplies zero-valued guidance; it does not remove the guidance field or disable the node.

HunyuanImage 3.0 Guidance Output Parameters:

CONDITIONING

The modified CONDITIONING data, ready to pass onward to a compatible generation workflow. It contains the same number of conditioning entries, in the same order, with their original encoded content preserved. Each entry has copied metadata containing a guidance field whose value is a single-element bfloat16 tensor holding 1000.0 * guidance_scale. Any previous guidance value is overwritten, while unrelated metadata remains intact. This output is not an image, latent, or modified model; it carries the model-specific guidance information alongside the existing conditioning so that downstream components can provide it to the Instruct-Distil model.

HunyuanImage 3.0 Guidance Usage Tips:

  • Use this node with the HunyuanImage 3.0 Instruct-Distil checkpoint. Its description explicitly limits the intended use to that variant, so do not assume other HunyuanImage checkpoints or unrelated models interpret this guidance correctly.
  • Start with guidance_scale set to 2.5 and keep the sampler’s cfg at 1.0. These are the settings identified by the node description for this guidance method; sampler CFG is a separate mechanism, not a substitute for this setting.
  • Place the node after compatible conditioning preparation and connect its CONDITIONING output to the conditioning path used for generation. Connecting only the original conditioning downstream bypasses the guidance information added here.
  • Enter guidance in the displayed scale, without multiplying it yourself. For example, enter 2.5 rather than 2500, because the node performs the internal conversion automatically.
  • When experimenting, change guidance gradually around 2.5 while keeping your prompt, seed, sampler, and other generation settings fixed. This makes it easier to judge the effect without assuming that larger values necessarily improve the result.
  • Avoid stacking several instances expecting their guidance strengths to add together. Each instance replaces the existing guidance field, so the final instance determines the stored guidance value.
  • If you need different guidance settings for separate conditioning branches, apply the node separately to each branch. A single instance applies one shared setting to every entry it receives.

HunyuanImage 3.0 Guidance Common Errors and Solutions:

Required input missing: conditioning or guidance_scale

  • Explanation: Both inputs are required by the interface. ComfyUI may stop workflow validation if a required connection or value is absent; the exact validation message depends on your ComfyUI version.
  • Solution: Connect compatible CONDITIONING data to conditioning and ensure guidance_scale has a numeric value. Use 2.5 as your initial guidance setting.

Input type mismatch for conditioning

  • Explanation: The node expects CONDITIONING data, not a plain-text string, IMAGE, LATENT, or MODEL connection. ComfyUI will generally prevent incompatible connections or report a validation problem.
  • Solution: Encode your prompt using a compatible conditioning node first, then connect its CONDITIONING output here. Do not connect raw prompt text or image data directly.

Value outside the allowed range for guidance_scale

  • Explanation: The schema permits values from 0.0 through 100.0. Values outside that range can fail validation, particularly when supplied through an API or an edited workflow.
  • Solution: Supply a numeric value within the declared range. If you entered 2500 to represent the checkpoint’s recommended guidance, replace it with 2.5; the node handles scaling internally.

ValueError: not enough values to unpack / too many values to unpack

  • Explanation: These Python errors can occur if malformed conditioning reaches the node. Its processing expects each conditioning entry to contain exactly two parts: encoded content and associated metadata.
  • Solution: Reconnect conditioning from a compatible encoder and temporarily bypass custom nodes that manually alter its structure. In API workflows, preserve the standard conditioning structure rather than constructing entries from plain text.

TypeError when copying conditioning metadata

  • Explanation: The node copies each entry’s metadata using dict(meta). If a custom workflow supplies metadata that cannot be converted to a dictionary, execution can fail with a TypeError or ValueError; the exact message depends on the malformed value.
  • Solution: Use conditioning from a compatible encoder and check any intermediate nodes that modify metadata. Restore dictionary-style metadata rather than supplying a number, null value, or unrelated object.

Guidance appears ineffective or results are unexpected

  • Explanation: This is a troubleshooting symptom rather than an error message raised by the node. Possible causes include using a checkpoint other than Instruct-Distil, leaving sampler CFG above 1.0, or routing the original conditioning to generation instead of the node’s output.
  • Solution: Verify the checkpoint variant, set guidance_scale to 2.5 and sampler cfg to 1.0, and trace the connections to confirm that generation receives this node’s CONDITIONING output. Then test changes with a fixed seed.

Earlier guidance settings seem to be ignored

  • Explanation: This is expected if another instance of this node appears later in the same conditioning path. The implementation replaces the guidance metadata field rather than combining guidance values.
  • Solution: Keep one guidance node per conditioning path unless replacement is intentional, and configure the last instance with the setting you want the model to receive.

HunyuanImage 3.0 Guidance Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-HunyuanImage3
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

HunyuanImage 3.0 Guidance