sgl-project/sglang · error · ValueError

{transformer_cls_name} is not officially supported by cache-

Error message

{transformer_cls_name} is not officially supported by cache-dit. Supported cache-dit DiT families include Flux, QwenImage, HunyuanDiT, HunyuanVideo, Wan, CogVideoX, Mochi, and others. Please ensure your transformer belongs to one of these families or define a custom BlockAdapter.

What it means

Raised by enable_cache_on_transformer when the given DiT transformer class is not recognized by cache-dit's BlockAdapterRegister and no custom BlockAdapter could be auto-built for it. cache-dit accelerates inference by caching intermediate block outputs, which requires knowing the model's block structure via an adapter; unsupported architectures cannot be cached safely. The error lists the officially supported families (Flux, QwenImage, HunyuanDiT, HunyuanVideo, Wan, CogVideoX, Mochi, etc.).

Source

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

        return transformer

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

    # Prefer the standard path (transformer pre-registered in cache-dit). For
    # models absent from the registry, fall back to a manual BlockAdapter (see
    # _build_custom_block_adapter).
    custom_adapter = None
    if not BlockAdapterRegister.is_supported(transformer):
        custom_adapter = _build_custom_block_adapter(
            transformer, has_separate_cfg=has_separate_cfg
        )
        if custom_adapter is None:
            transformer_cls_name = transformer.__class__.__name__
            raise ValueError(
                f"{transformer_cls_name} is not officially supported by cache-dit. "
                "Supported cache-dit DiT families include Flux, QwenImage, HunyuanDiT, "
                "HunyuanVideo, Wan, CogVideoX, Mochi, and others. "
                "Please ensure your transformer belongs to one of these families or "
                "define a custom BlockAdapter."
            )

    # Build cache config (including SCM fields if provided)
    cache_config = DBCacheConfig(
        num_inference_steps=config.num_inference_steps,
        Fn_compute_blocks=config.Fn_compute_blocks,
        Bn_compute_blocks=config.Bn_compute_blocks,
        max_warmup_steps=config.max_warmup_steps,
        residual_diff_threshold=config.residual_diff_threshold,
        max_continuous_cached_steps=config.max_continuous_cached_steps,
        # SCM fields
        steps_computation_mask=config.steps_computation_mask,
        steps_computation_policy=config.steps_computation_policy,

View on GitHub (pinned to 0132848349)

Solutions

1. Disable cache-dit for this model (set enabled=False in CacheDitConfig) so the transformer runs uncached
2. Register a custom BlockAdapter for your transformer class via cache-dit's BlockAdapterRegister before calling enable_cache_on_transformer
3. Ensure the transformer is loaded from a supported family checkpoint (e.g. a Flux/QwenImage/Wan class) and that wrappers do not obscure the underlying class
4. Upgrade sglang and cache-dit to a version that adds adapter support for your model family

Example fix

# before
config = CacheDitConfig(enabled=True)
transformer, _ = enable_cache_on_transformer(transformer, config)  # ValueError

# after
config = CacheDitConfig(enabled=False)  # run without cache-dit
transformer, _ = enable_cache_on_transformer(transformer, config)

# or: define and register a custom adapter
class MyDiTAdapter(cache_dit.BlockAdapter):
    ...
cache_dit.BlockAdapterRegister.add_adapter(MyTransformer, MyDiTAdapter)

from sglang.multimodal_gen.runtime.cache.cache_dit_integration import BlockAdapterRegister, _build_custom_block_adapter

def can_cache(transformer) -> bool:
    return BlockAdapterRegister.is_supported(transformer) or \
           _build_custom_block_adapter(transformer, has_separate_cfg=False) is not None

if not can_cache(transformer):
    config = CacheDitConfig(enabled=False)

try:
    transformer, _ = enable_cache_on_transformer(transformer, config)
except ValueError as e:
    if "not officially supported by cache-dit" in str(e):
        logger.warning("cache-dit disabled: %s", e)
        config = CacheDitConfig(enabled=False)  # fall back to uncached
    else:
        raise

When it happens

Trigger: Calling enable_cache_on_transformer(transformer, ...) (usually via the runtime's _maybe_enable_cache_dit when cache-dit is enabled in CacheDitConfig) with a custom or newer transformer class whose family is not in BlockAdapterRegister and for which _build_custom_block_adapter returns None (no detectable blocks attribute / heuristics fail).

Common situations: Loading a custom fine-tuned DiT variant, a brand-new model release before adapter support lands, renaming/wrapping the transformer so class-name detection fails, or upgrading cache-dit where supported-family registration changed.

Related errors

• Transformer {transformer.__class__.__name__} has no attribut
• Dual-transformer cache-dit is only supported for {sorted(DUA
• cache_dit_params must be a dict, got {type(raw).__name__}.
• Unknown cache_dit_params keys: {sorted(unknown)}. Valid keys
• cache_dit_params['secondary'] must be a dict, got {type(seco

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