Deploy Qwen Image

Cause: Newer models replaced CLIP/T5 with a full LLM encoder. LTX-2 19B's LTXVGemmaCLIPModelLoader wants a DIRECTORY encoder: weights come from the non-gated Comfy-Org/ltx-2 repo, but config.json + tokenizer.model come from the GATED google/gemma-3-12b-it repo — without HF token + accepted license the sidecar 403s and the loader sees an empty list.

Fix: Supply HF token + accept the Gemma license so the gated config/tokenizer sidecar downloads into the encoder directory. Note LTX-2.3's default graph instead uses a single-file FP4 encoder (gemma_3_12B_it_fp4_mixed, non-gated, no tokenizer sidecar).

Cause: FLUX.2 dropped FLUX.1's dual T5-XXL+CLIP_L for a single Mistral-3-Small encoder (18GB fp8 / 36GB bf16) — and the smaller Klein 4B/9B variants use a Qwen-3 encoder instead. The encoder stack isn't stable across versions or even size tiers of one release.

Fix: Match encoder files to the exact variant (mistral*3_small_flux2 for FLUX.2 dev; qwen_3*\* for Klein). Don't reuse the previous version's encoders.

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: Z-Image Turbo is a photoreal-leaning generalist, not an anime model; Z-Anime (SeeSee21 fine-tune) is a separate community model on the identical architecture and loads via the same zimage deploy path. Encoder architecture is Qwen-3-4B, VAE = Flux's ae.safetensors (335MB). fp8 diffusion 6.15GB (fits 12GB), bf16 12.3GB; GGUF Q3-Q8 for low VRAM.

Fix: A Turbo base and its fine-tunes share architecture + VAE (and the Qwen-3-4B encoder architecture — a fine-tune may ship its own tuned encoder weights, e.g. Z-Anime's qwen_3_4b-engineer-v4-fp8), so one zimage deploy path serves both.

Cause: Unpinned by default: models pull from floating HF /resolve/main (branch HEAD), custom nodes are git-clone-latest (no SHA), Docker tags are reused, and only ~95% file-size is validated, not content hash. An upstream re-upload or newer node code silently changed bytes/behavior behind unchanged names.

Fix: Pin weights to a commit/revision, nodes to a SHA, images to a digest. Verify a pinned HF URL with `curl -sI -r 0-0 -A 'Mozilla/5.0' -L '<url>'` — MUST include -L (HF /resolve/ 302-redirects to a CDN; without -L you see 302 not 206).

Cause: The node was pinned to a commit predating when the required node class was added upstream. (The inverse also bites: a too-NEW pin can fail to import, forcing a rollback to an older release.)

Fix: Two-sided constraint: pin new enough that EVERY referenced node class is registered, but NOT so new it needs a ComfyUI newer than the baked image. Verify the pinned commit's NODE_CLASS_MAPPINGS registers all referenced classes AND imports cleanly against the deployed ComfyUI.