sgl-project/sglang · critical · ValueError

Z-Image transformer has no `rotary_emb`. It likely loaded vi

Error message

Z-Image transformer has no `rotary_emb`. It likely loaded via the native diffusers fallback; check the load logs for the real error.

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/configs/pipeline_configs/zimage.py:371

    def get_freqs_cis(
        self,
        prompt_embeds,
        width,
        height,
        device,
        rotary_emb,
        batch,
        *,
        negative: bool = False,
    ):
        """Build caption and image RoPE caches for Z-Image conditioning.

        Batched prompts use stored text lengths. SP mode builds image caches for
        the local spatial shard.
        """
        if rotary_emb is None:
            raise ValueError(
                "Z-Image transformer has no `rotary_emb`. It likely loaded via the "
                "native diffusers fallback; check the load logs for the real error."
            )

        def create_coordinate_grid(size, start=None, device=None):
            if start is None:
                start = (0 for _ in size)

            axes = [
                torch.arange(x0, x0 + span, dtype=torch.int32, device=device)
                for x0, span in zip(start, size)
            ]
            grids = torch.meshgrid(axes, indexing="ij")
            return torch.stack(grids, dim=-1)

        sp_size = get_sp_world_size()
        if sp_size > 1:
            # SP path: keep caption replicated on every rank and build local-only

View on GitHub (pinned to 0132848349)

Solutions

  1. Search the server/model load logs for the original load error that triggered the diffusers fallback and fix that first
  2. Ensure the Z-Image checkpoint and native loader dependencies are complete/compatible (re-download weights if truncated, pin matching versions)
  3. Retry with the native loader explicitly (disable the fallback) so the real load failure surfaces directly
  4. If forced to use the fallback, note RoPE cache construction is unsupported and the native path is required for this pipeline
Defensive patterns

Strategy: try-catch

Validate before calling

rotary = getattr(transformer, "rotary_emb", None)
if rotary is None:
    logger.warning("transformer loaded via diffusers fallback; RoPE cond kwargs unavailable")

Type guard

def has_native_rotary(transformer) -> bool:
    return getattr(transformer, "rotary_emb", None) is not None

Try / catch

try:
    cond_kwargs = cfg.get_freqs_cis(...)
except ValueError as e:
    if "rotary_emb" in str(e):
        raise RuntimeError("native Z-Image load failed; inspect startup logs") from e
    raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/02534f057c7cb79b. Report an issue: GitHub.