{"record":{"id":"1bd5bfb7cebcaedc","repo":"sgl-project/sglang","slug":"dual-transformer-cache-dit-is-only-supported-for","errorCode":null,"errorMessage":"Dual-transformer cache-dit is only supported for {sorted(DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS)}, got {model_name}.","messagePattern":"Dual-transformer cache-dit is only supported for (.+?), got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/cache/cache_dit_integration.py","lineNumber":554,"sourceCode":"    sp_group: Optional[torch.distributed.ProcessGroup] = None,\n    tp_group: Optional[torch.distributed.ProcessGroup] = None,\n) -> tuple[torch.nn.Module, torch.nn.Module]:\n    \"\"\"Enable cache-dit on dual transformers using BlockAdapter.\n\n    For models with two transformers, cache-dit requires enabling cache on both\n    simultaneously via BlockAdapter. The two transformers may be split by denoising\n    range, or run as paired conditional/unconditional branches. This cannot be done\n    by calling enable_cache separately on each transformer.\n\n    Args:\n        primary_config: CacheDitConfig for primary transformer.\n        secondary_config: CacheDitConfig for secondary transformer.\n        sp_group: Sequence parallel process group (for Ulysses/Ring).\n        tp_group: Tensor parallel process group.\n    \"\"\"\n    adapter_spec = DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS.get(model_name)\n    if adapter_spec is None:\n        raise ValueError(\n            f\"Dual-transformer cache-dit is only supported for \"\n            f\"{sorted(DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS)}, got {model_name}.\"\n        )\n\n    if not primary_config.enabled:\n        return transformer, transformer_2\n\n    if primary_config.num_inference_steps is None:\n        raise ValueError(\n            \"num_inference_steps is required for dual-transformer mode. \"\n            \"Please provide it in CacheDitConfig.\"\n        )\n\n    # Build DBCacheConfig for primary transformer\n    primary_cache_config = DBCacheConfig(\n        num_inference_steps=primary_config.num_inference_steps,\n        Fn_compute_blocks=primary_config.Fn_compute_blocks,\n        Bn_compute_blocks=primary_config.Bn_compute_blocks,","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/cache/cache_dit_integration.py#L536-L572","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS keys and pass the exact canonical model_name from that dict","Disable cache-dit for this dual-transformer model (enabled=False in CacheDitConfig)","Register a DualTransformerBlockAdapterSpec entry for your model in the specs mapping (if extending the library)","Upgrade sglang so the model's dual-transformer spec exists"],"exampleFix":"# before\nenable_cache_on_dual_transformer(t1, t2, model_name=\"flux-dual\", ...)  # ValueError\n\n# after\nfrom sglang.multimodal_gen.runtime.cache.cache_dit_integration import DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS\nassert model_name in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS, sorted(DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS)\nenable_cache_on_dual_transformer(t1, t2, model_name=model_name, ...)","handlingStrategy":"validation","validationCode":"from sglang.multimodal_gen.runtime.cache.cache_dit_integration import DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS\n\nif model_name not in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS:\n    raise ConfigError(\n        f\"{model_name} not cacheable; pick from {sorted(DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS)}\")\n# or: config.cache_dit.enabled = model_name in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS","typeGuard":"def is_dual_cacheable(model_name: str) -> bool:\n    from sglang.multimodal_gen.runtime.cache.cache_dit_integration import DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS\n    return model_name in DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS","tryCatchPattern":"try:\n    t1, t2 = enable_cache_on_dual_transformer(t1, t2, model_name, cfg, ...)\nexcept ValueError as e:\n    if \"Dual-transformer cache-dit is only supported for\" in str(e):\n        run_without_cache_dit()  # fallback\n    else:\n        raise","preventionTips":["Derive model_name from the registry keys, never hand-type it in configs","Validate the name against DUAL_TRANSFORMER_BLOCK_ADAPTER_SPECS at config load time","Add a unit test asserting your served models are covered by the specs"],"tags":["cache-dit","dual-transformer","model-name-registry","valueerror"],"backgroundTag":"unknown-registry-key","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}