{"record":{"id":"970d903577d9d96a","repo":"sgl-project/sglang","slug":"num-inference-steps-is-required-for-transformer-on","errorCode":null,"errorMessage":"num_inference_steps is required for transformer-only mode. Please provide it in CacheDitConfig.","messagePattern":"num_inference_steps is required for transformer-only mode\\. Please provide it in CacheDitConfig\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/cache/cache_dit_integration.py","lineNumber":419,"sourceCode":"    \"\"\"Enable cache-dit on a transformer module, by wrapping the module with cache-dit\n\n    This function enables cache-dit acceleration using the BlockAdapterRegister\n    for pre-registered models\n\n    Args:\n        model_name: Name of the model for logging purposes.\n        sp_group: Sequence parallel process group (for Ulysses/Ring).\n        tp_group: Tensor parallel process group.\n        has_separate_cfg: Whether the run issues separate conditional/unconditional\n            passes per step (CFG). Used by custom adapters (ERNIE, Krea-2); a\n            mismatch only disables caching, never corrupts output.\n\n    \"\"\"\n    if not config.enabled:\n        return transformer\n\n    if config.num_inference_steps is None:\n        raise ValueError(\n            \"num_inference_steps is required for transformer-only mode. \"\n            \"Please provide it in CacheDitConfig.\"\n        )\n\n    # Prefer the standard path (transformer pre-registered in cache-dit). For\n    # models absent from the registry, fall back to a manual BlockAdapter (see\n    # _build_custom_block_adapter).\n    custom_adapter = None\n    if not BlockAdapterRegister.is_supported(transformer):\n        custom_adapter = _build_custom_block_adapter(\n            transformer, has_separate_cfg=has_separate_cfg\n        )\n        if custom_adapter is None:\n            transformer_cls_name = transformer.__class__.__name__\n            raise ValueError(\n                f\"{transformer_cls_name} is not officially supported by cache-dit. \"\n                \"Supported cache-dit DiT families include Flux, QwenImage, HunyuanDiT, \"\n                \"HunyuanVideo, Wan, CogVideoX, Mochi, and others. \"","sourceCodeStart":401,"sourceCodeEnd":437,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/cache/cache_dit_integration.py#L401-L437","documentation":"enable_cache_on_transformer returns early when config.enabled is false; otherwise, in transformer-only mode (no full pipeline object), cache-dit needs the total number of inference steps known up front, so config.num_inference_steps is None raises immediately with this ValueError.","triggerScenarios":"Constructing CacheDitConfig(enabled=True) without num_inference_steps and calling enable_cache_on_transformer (typically via _maybe_enable_cache_dit when cache-dit is enabled for a transformer-only runtime).","commonSituations":"Enabling cache_dit with only request-side overrides and forgetting the server-level step count; switching a deployment from pipeline mode (where steps come from the pipeline) to transformer-only mode; step counts not plumbed from the scheduler into the config.","solutions":["Set num_inference_steps in CacheDitConfig to match the sampling steps used for requests, e.g. CacheDitConfig(enabled=True, num_inference_steps=50).","Plumb the scheduler's/sampler's step count into the config before enabling cache-dit.","Disable cache-dit (enabled=False) if you cannot fix the step count."],"exampleFix":"// before\nconfig = CacheDitConfig(enabled=True)\nenable_cache_on_transformer(transformer, config)\n// after\nconfig = CacheDitConfig(enabled=True, num_inference_steps=50)\nenable_cache_on_transformer(transformer, config)","handlingStrategy":"validation","validationCode":"if config.enabled and getattr(config, \"num_inference_steps\", None) is None:\n    raise ValueError(\"set num_inference_steps before enabling cache-dit\")\nenable_cache_on_transformer(transformer, config)","typeGuard":"def cache_dit_config_valid(config) -> bool:\n    return (not config.enabled) or config.num_inference_steps is not None","tryCatchPattern":"try:\n    enable_cache_on_transformer(transformer, config)\nexcept ValueError as e:\n    if \"num_inference_steps is required\" in str(e):\n        config = replace(config, num_inference_steps=sampler_steps)\n        retry(enable_cache_on_transformer, transformer, config)\n    raise","preventionTips":["Always construct CacheDitConfig(enabled=True) together with num_inference_steps.","Keep the configured steps in sync with request-time sampling steps.","Add a startup assertion validating the config when cache-dit is enabled."],"tags":["cache-dit","missing-config","inference-steps","transformer-only"],"backgroundTag":"missing-required-config-field","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}