{"record":{"id":"02534f057c7cb79b","repo":"sgl-project/sglang","slug":"z-image-transformer-has-no-rotary-emb-it-likely","errorCode":null,"errorMessage":"Z-Image transformer has no `rotary_emb`. It likely loaded via the native diffusers fallback; check the load logs for the real error.","messagePattern":"Z-Image transformer has no `rotary_emb`\\. It likely loaded via the native diffusers fallback; check the load logs for the real error\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"python/sglang/multimodal_gen/configs/pipeline_configs/zimage.py","lineNumber":371,"sourceCode":"\n    def get_freqs_cis(\n        self,\n        prompt_embeds,\n        width,\n        height,\n        device,\n        rotary_emb,\n        batch,\n        *,\n        negative: bool = False,\n    ):\n        \"\"\"Build caption and image RoPE caches for Z-Image conditioning.\n\n        Batched prompts use stored text lengths. SP mode builds image caches for\n        the local spatial shard.\n        \"\"\"\n        if rotary_emb is None:\n            raise ValueError(\n                \"Z-Image transformer has no `rotary_emb`. It likely loaded via the \"\n                \"native diffusers fallback; check the load logs for the real error.\"\n            )\n\n        def create_coordinate_grid(size, start=None, device=None):\n            if start is None:\n                start = (0 for _ in size)\n\n            axes = [\n                torch.arange(x0, x0 + span, dtype=torch.int32, device=device)\n                for x0, span in zip(start, size)\n            ]\n            grids = torch.meshgrid(axes, indexing=\"ij\")\n            return torch.stack(grids, dim=-1)\n\n        sp_size = get_sp_world_size()\n        if sp_size > 1:\n            # SP path: keep caption replicated on every rank and build local-only","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/configs/pipeline_configs/zimage.py#L353-L389","documentation":"Z-Image's transformer is expected to expose a rotary_emb module used to build RoPE caches. If rotary_emb is None, the transformer was almost certainly loaded through the native diffusers fallback path rather than the SGLang-native loader, indicating the native load failed earlier. This error is a symptom; the root cause is in the load logs.","triggerScenarios":"Calling prepare_pos_cond_kwargs or prepare_neg_cond_kwargs (which call get_freqs_cis) after the Z-Image transformer was loaded via the diffusers fallback because the native loader errored or was unavailable.","commonSituations":"Native weight conversion/loading fails silently and falls back; incompatible diffusers/sglang versions; corrupted or partial checkpoint download; a missing load-time dependency making the native path bail out.","solutions":["Search the server/model load logs for the original load error that triggered the diffusers fallback and fix that first","Ensure the Z-Image checkpoint and native loader dependencies are complete/compatible (re-download weights if truncated, pin matching versions)","Retry with the native loader explicitly (disable the fallback) so the real load failure surfaces directly","If forced to use the fallback, note RoPE cache construction is unsupported and the native path is required for this pipeline"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"rotary = getattr(transformer, \"rotary_emb\", None)\nif rotary is None:\n    logger.warning(\"transformer loaded via diffusers fallback; RoPE cond kwargs unavailable\")","typeGuard":"def has_native_rotary(transformer) -> bool:\n    return getattr(transformer, \"rotary_emb\", None) is not None","tryCatchPattern":"try:\n    cond_kwargs = cfg.get_freqs_cis(...)\nexcept ValueError as e:\n    if \"rotary_emb\" in str(e):\n        raise RuntimeError(\"native Z-Image load failed; inspect startup logs\") from e\n    raise","preventionTips":["Scan load logs for 'fallback' markers at startup and fail fast","Pin sglang/diffusers versions validated for Z-Image native loading","Verify checkpoint integrity (hash/file count) before load"],"tags":["z-image","model-loading","fallback","rotary-embeddings","diffusers"],"backgroundTag":"model-load-fallback-misconfiguration","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}