{"record":{"id":"eda396174a34721b","repo":"sgl-project/sglang","slug":"z-image-expects-one-caption-embedding-per-image-g","errorCode":null,"errorMessage":"Z-Image expects one caption embedding per image, got {len(all_image)} images and {len(all_cap_feats)} captions","messagePattern":"Z-Image expects one caption embedding per image, got (.+?) images and (.+?) captions","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/dits/zimage.py","lineNumber":971,"sourceCode":"    def patchify_and_embed(\n        self,\n        all_image: List[torch.Tensor],\n        all_cap_feats: List[torch.Tensor],\n        patch_size: int,\n        f_patch_size: int,\n        image_seq_len_target: int | None = None,\n        caption_valid_lens: torch.Tensor | None = None,\n        caption_valid_mask: torch.Tensor | None = None,\n    ):\n        \"\"\"Patchify images and pad image/caption tokens to batch targets.\n\n        Each image is [C, F, H, W] and has one [L, D] caption. Returned tensors\n        are stacked as [B, S, D], while valid lengths keep track of real tokens\n        before learned pad tokens are restored. `image_seq_len_target`, when\n        set, is the SP-local padded image-token target.\n        \"\"\"\n        if len(all_image) != len(all_cap_feats):\n            raise ValueError(\n                f\"Z-Image expects one caption embedding per image, got {len(all_image)} images and {len(all_cap_feats)} captions\"\n            )\n        if not all_image:\n            raise ValueError(\"Z-Image batch must contain at least one image latent\")\n        if caption_valid_mask is not None and caption_valid_mask.shape[0] != len(\n            all_cap_feats\n        ):\n            raise ValueError(\"caption_valid_mask must have one row per Z-Image caption\")\n\n        pH = pW = patch_size\n        pF = f_patch_size\n        all_image_out = []\n        all_image_size = []\n        all_cap_feats_out = []\n        all_image_valid_lens = []\n        all_cap_valid_lens = []\n        all_cap_valid_masks = []\n        all_image_attn_lens = []","sourceCodeStart":953,"sourceCodeEnd":989,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/dits/zimage.py#L953-L989","documentation":"Raised by ZImage.patchify_and_embed when the number of image latents in all_image differs from the number of caption embeddings in all_cap_feats. The model pairs each image with exactly one caption embedding; a length mismatch means the batch assembly is inconsistent.","triggerScenarios":"Calling the Z-Image forward with 2 image latents but 3 caption feature tensors (or vice versa), typically from a batching routine that zips/pads images and captions separately.","commonSituations":"Batching routine drops an image when its latent fails to encode but keeps the caption; mis-indexed caption list after filtering invalid samples.","solutions":["Make the batching code build (image, caption) pairs and never filter one side independently","Assert len(all_image) == len(all_cap_feats) before calling forward","Check upstream filtering logic that removed failed latents or captions"],"exampleFix":"# before\nall_image = [img for img, ok in zip(imgs, oks) if ok]\nall_cap_feats = caps  # kept all\n# after\npairs = [(img, cap) for img, cap, ok in zip(imgs, caps, oks) if ok]\nall_image = [p[0] for p in pairs]\nall_cap_feats = [p[1] for p in pairs]","handlingStrategy":"validation","validationCode":"assert len(all_image) == len(all_cap_feats), \"image/caption count mismatch\"","typeGuard":"def batch_pairs_aligned(images: list, caps: list) -> bool:\n    return len(images) == len(caps)","tryCatchPattern":null,"preventionTips":["Build batches as (image, caption) pairs so the two lists cannot diverge"],"tags":["z-image","batching","shape-validation"],"backgroundTag":"batch-length-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}