sgl-project/sglang · error · ValueError

Dual-transformer cache-dit is only supported for {sorted(DUA

Error message

Dual-transformer cache-dit is only supported for {sorted(DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS)}, got {model_name}.

What it means

Raised by enable_cache_on_dual_transformer when cache-dit is requested for a dual-transformer (primary + secondary, e.g. text encoder + denoiser or MoE-style split) model whose model_name is not in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS. Dual-transformer caching needs per-model knowledge of where the block lists live on each transformer, so only explicitly registered model names are allowed.

Source

Thrown at python/sglang/multimodal_gen/runtime/cache/cache_dit_integration.py:554

    sp_group: Optional[torch.distributed.ProcessGroup] = None,
    tp_group: Optional[torch.distributed.ProcessGroup] = None,
) -> tuple[torch.nn.Module, torch.nn.Module]:
    """Enable cache-dit on dual transformers using BlockAdapter.

    For models with two transformers, cache-dit requires enabling cache on both
    simultaneously via BlockAdapter. The two transformers may be split by denoising
    range, or run as paired conditional/unconditional branches. This cannot be done
    by calling enable_cache separately on each transformer.

    Args:
        primary_config: CacheDitConfig for primary transformer.
        secondary_config: CacheDitConfig for secondary transformer.
        sp_group: Sequence parallel process group (for Ulysses/Ring).
        tp_group: Tensor parallel process group.
    """
    adapter_spec = DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS.get(model_name)
    if adapter_spec is None:
        raise ValueError(
            f"Dual-transformer cache-dit is only supported for "
            f"{sorted(DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS)}, got {model_name}."
        )

    if not primary_config.enabled:
        return transformer, transformer_2

    if primary_config.num_inference_steps is None:
        raise ValueError(
            "num_inference_steps is required for dual-transformer mode. "
            "Please provide it in CacheDitConfig."
        )

    # Build DBCacheConfig for primary transformer
    primary_cache_config = DBCacheConfig(
        num_inference_steps=primary_config.num_inference_steps,
        Fn_compute_blocks=primary_config.Fn_compute_blocks,
        Bn_compute_blocks=primary_config.Bn_compute_blocks,

View on GitHub (pinned to 0132848349)

Solutions

1. Check DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS keys and pass the exact canonical model_name from that dict
2. Disable cache-dit for this dual-transformer model (enabled=False in CacheDitConfig)
3. Register a DualTransformerBlockAdapterSpec entry for your model in the specs mapping (if extending the library)
4. Upgrade sglang so the model's dual-transformer spec exists

Example fix

# before
enable_cache_on_dual_transformer(t1, t2, model_name="flux-dual", ...)  # ValueError

# after
from sglang.multimodal_gen.runtime.cache.cache_dit_integration import DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS
assert model_name in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS, sorted(DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS)
enable_cache_on_dual_transformer(t1, t2, model_name=model_name, ...)

from sglang.multimodal_gen.runtime.cache.cache_dit_integration import DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS

if model_name not in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS:
    raise ConfigError(
        f"{model_name} not cacheable; pick from {sorted(DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS)}")
# or: config.cache_dit.enabled = model_name in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS

def is_dual_cacheable(model_name: str) -> bool:
    from sglang.multimodal_gen.runtime.cache.cache_dit_integration import DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS
    return model_name in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS

try:
    t1, t2 = enable_cache_on_dual_transformer(t1, t2, model_name, cfg, ...)
except ValueError as e:
    if "Dual-transformer cache-dit is only supported for" in str(e):
        run_without_cache_dit()  # fallback
    else:
        raise

When it happens

Trigger: Calling enable_cache_on_dual_transformer(transformer, transformer_2, model_name, ...) with a model_name key that has no entry in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS (typically invoked from _maybe_enable_cache_dit when a dual-transformer model is loaded with caching enabled).

Common situations: Passing a raw checkpoint name instead of the canonical registry key (wrong casing/spelling), using a newly added dual-transformer model before its spec was registered, or a version mismatch between the model registry and the cache-dit integration.

Related errors

• {transformer_cls_name} is not officially supported by cache-
• num_inference_steps is required for dual-transformer mode. P
• Dual transformers for {model_name} must expose cache-dit blo
• cache_dit_params must be a dict, got {type(raw).__name__}.
• Unknown cache_dit_params keys: {sorted(unknown)}. Valid keys

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