Deploy HunyuanVideo

Cause: Encoder count is model-specific and modern models pair a small CLIP with a large, easy-to-forget LLM/VL encoder: HiDream's QuadrupleCLIPLoader needs FOUR (incl. llama-3.1-8b fp8_scaled ~8.5GB); HunyuanVideo needs DUAL (clip_l + llava_llama3, +vision for i2v); Qwen-Image needs Qwen-2.5-VL-7B (~7GB fp8 to ~16GB bf16); Z-Image needs Qwen-3-4B (8GB). A 'not in list' error usually means you shipped N-1.

Fix: Ship the full encoder set for the exact model; the missing piece is almost always the large LLM/VL encoder, not the CLIP.

Cause: A truncated safetensors fails cleanly (reads an 8-byte header-length prefix then expects that many bytes). The shared validator (validate_download in download_utils.sh) only checks non-empty/not-HTML, so a truncated file passes and is cached forever; wget's exit code is unreliable through HF CDN redirects. Some scripts have too-low size floors (hunyuan MIN_SIZE_DIFFUSION=12GB for a ~25GB model would pass a ~50%-truncated file).

Fix: Validate by size against per-variant expected content-length (sha256 ideally). On MetadataIncompleteBuffer, delete the cached file and redownload. Lead with the safetensors error; opaque CUDA/NaN is the corrupt-but-not-truncated secondary case.

Cause: The driving clip wasn't real full-body human motion (e.g. abstract light-art/VFX), so DWPose extracts no valid skeleton. Motion-transfer models faithfully reproduce whatever motion is actually in the driver; a bad driver yields empty/nonsensical conditioning no subject tuning can fix.

Fix: QA the DRIVER frame-by-frame first — it must contain a clearly-tracked full-body human. The reference/mask/background can look fine while the pose track is empty.

Cause: `skip_first_frames` is applied in the frame domain produced by `force_rate`. With `force_rate=16`, skip 145 means about 9.06 seconds even when the source file is 25 fps; treating it as source frame 145 incorrectly predicts a 5.8-second start.

Fix: Pre-trim and pre-resample the exact driver segment locally, upload that asset, and set `skip_first_frames=0`. If runtime skipping is necessary, calculate the skip against the forced output rate, not the source rate.

Cause: The graph's context window is 77 frames with an overlap start at frame 76. Loading 81 frames creates windows `0-77` and `76-153`; the second window is padded to full length and the combined output is not truncated to the driver's original frame count.

Fix: Cap bounded controls at 77 frames. For intentional long-form runs, retain overlapping windows but truncate the final encoded output to the actual driver frame count. Treat raw padded duration as an implementation artifact, not valid long-motion evidence.

Cause: (a) SAM2 seed points cover only torso/legs so out-of-mask source pixels (including the face) survive; (b) SAM2 is seeded on a title card or solid-color frame and propagates a meaningless mask; (c) positive points are reused from a differently framed driver and land on background. In the showcase orchestrator, normalized config coordinates are expanded into raw pixels against the driving video's actual width and height; they index driver frame zero, not the subject reference image.

Fix: Seed on a frame showing real content; overlay every positive point on driver frame zero; ensure every point hits the intended replace subject, including head and limbs; make PointsEditor canvas dimensions match the driver frame; inspect the blacked-out background preview before sampling.