{"record":{"id":"f69dc3b1b1605016","repo":"sgl-project/sglang","slug":"enable-unified-memory-supports-monolithic-decod","errorCode":null,"errorMessage":"--enable-unified-memory supports monolithic (decode) cuda-graph capture only; disable piecewise prefill capture (e.g. --cuda-graph-backend-prefill=disabled).","messagePattern":"--enable-unified-memory supports monolithic \\(decode\\) cuda-graph capture only; disable piecewise prefill capture \\(e\\.g\\. --cuda-graph-backend-prefill=disabled\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":9359,"sourceCode":"            )\n        assert not (cfg.enable_hierarchical_cache or cfg.enable_lmcache), (\n            \"--enable-unified-memory is not yet compatible with hierarchical / \"\n            \"host-tiered KV cache (--enable-hierarchical-cache / --enable-lmcache): \"\n            \"the unified-memory-pool init wires up no host pools, and its device mamba / \"\n            \"full-attention slots are VIRTUAL — the host-offload path does not \"\n            \"translate them to physical.\"\n        )\n        assert cfg.dcp_size == 1, (\n            \"--enable-unified-memory is not yet compatible with decode context \"\n            \"parallelism (--dcp-size > 1): the pool has no DCP-aware masked write \"\n            \"path (UnifiedMHATokenToKVPool.set_kv_buffer asserts dcp_kv_mask is None), \"\n            \"so a DCP run would boot and then fail on the first KV write.\"\n        )\n        # Only monolithic decode cuda-graph capture is wired; piecewise prefill\n        # capture is not. Guard when the user opts into it.\n        _cg_cfg = cfg.cuda_graph_config\n        if _cg_cfg is not None and _cg_cfg.prefill.backend == Backend.TC_PIECEWISE:\n            raise ValueError(\n                \"--enable-unified-memory supports monolithic (decode) \"\n                \"cuda-graph capture only; disable piecewise prefill capture \"\n                \"(e.g. --cuda-graph-backend-prefill=disabled).\"\n            )\n        # The strided-layout Triton requirement is enforced via\n        # --enable-page-major-kv-layout (implied by the unified pool in\n        # _handle_page_major_kv_layout); the model-family gate is enforced at pool\n        # construction in model_runner_kv_cache_mixin._init_pools.\n\n    def _handle_page_major_kv_layout(self):\n        # The unified pool stores state in the page-major envelope-strided layout, so\n        # enabling it implies --enable-page-major-kv-layout — routing it through the\n        # single page-major path + stride-aware Triton asserts (set before the guard).\n        cfg = resolving_view(self)\n        if cfg.enable_unified_memory:\n            self._declare(\n                \"_handle_page_major_kv_layout\",\n                enable_page_major_kv_layout=True,","sourceCodeStart":9341,"sourceCodeEnd":9377,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L9341-L9377","documentation":"Raised when --enable-unified-memory (DCP/unified memory pool) is combined with piecewise (torch.compile) prefill CUDA-graph capture. Only monolithic decode-graph capture is wired for the unified-memory path; piecewise prefill capture is not, so the combination is rejected at startup.","triggerScenarios":"Passing --enable-unified-memory while cuda_graph_config.prefill.backend == TC_PIECEWISE (explicitly or via default when piecewise prefill capture is enabled).","commonSituations":"Enabling a global '--cuda-graph-backend piecewise' style flag alongside unified memory; newer SGLang defaulting prefill capture to piecewise; tuning both memory pooling and graph capture simultaneously.","solutions":["Disable prefill capture: --cuda-graph-backend-prefill=disabled","Or keep piecewise capture but drop --enable-unified-memory","Keep decode graph capture on (monolithic) which is supported"],"exampleFix":"# before\n--enable-unified-memory --cuda-graph-backend-prefill=piecewise\n# after\n--enable-unified-memory --cuda-graph-backend-prefill=disabled","handlingStrategy":"validation","validationCode":"if args.enable_unified_memory:\n    assert not (args.cuda_graph_config and args.cuda_graph_config.prefill.backend.name == 'TC_PIECEWISE'), \\\n        'unified memory requires monolithic graphs; set --cuda-graph-backend-prefill=disabled'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When enabling memory pooling flags, audit all cuda-graph flags for compatibility","Default launch scripts to --cuda-graph-backend-prefill=disabled on the unified-memory path"],"tags":["sglang","unified-memory","cuda-graph","prefill","piecewise"],"backgroundTag":"incompatible-feature-flags","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}