{"record":{"id":"582adb3d06ada66e","repo":"sgl-project/sglang","slug":"only-1-nextn-layer-is-supported-for-step3p5-checkp","errorCode":null,"errorMessage":"Only 1 nextn layer is supported for Step3p5 checkpoints.","messagePattern":"Only 1 nextn layer is supported for Step3p5 checkpoints\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/models/step3p5.py","lineNumber":946,"sourceCode":"            shard_id_matches = name_parts[4] == weight_parts[2]\n            return shard_id_matches\n\n        for name, loaded_weight in weights:\n            # Filter nextn layer weights.\n            if hasattr(self.config, \"num_nextn_predict_layers\"):\n                num_nextn_layers = getattr(self.config, \"num_nextn_predict_layers\", 0)\n                if num_nextn_layers and name.startswith(\"model.layers.\"):\n                    layer_id = _get_layer_id_from_weight_name(name)\n                    if layer_id is not None:\n                        if not is_nextn:\n                            # Normal load: skip layers appended after the main decoder.\n                            if layer_id >= self.config.num_hidden_layers:\n                                continue\n                        else:\n                            # nextn load: only keep the appended nextn layer.\n                            # (Only 1 nextn layer is supported by current checkpoints.)\n                            if num_nextn_layers != 1:\n                                raise ValueError(\n                                    \"Only 1 nextn layer is supported for Step3p5 checkpoints.\"\n                                )\n                            nextn_layer_id = (\n                                0\n                                if self.config.num_hidden_layers == 1\n                                else self.config.num_hidden_layers\n                            )\n                            if layer_id != nextn_layer_id:\n                                # # nextn/MTP load: only keep the appended nextn layers.\n                                # # Expected layer ids: [num_hidden_layers, num_hidden_layers + num_nextn_layers).\n                                # start = self.config.num_hidden_layers\n                                # end = self.config.num_hidden_layers + num_nextn_layers\n                                # if not (start <= layer_id < end):\n                                continue\n\n            for param_name, weight_name, shard_id in stacked_params_mapping:\n                if weight_name not in name:\n                    continue","sourceCodeStart":928,"sourceCodeEnd":964,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/models/step3p5.py#L928-L964","documentation":"Step3p5's MTP/nextn loading path assumes the checkpoint appends exactly one nextn (speculative draft) layer. If num_nextn_layers != 1 the loader refuses to proceed rather than mis-assigning layers.","triggerScenarios":"Loading a Step3p5 checkpoint whose spec.num_nextn_layers is 0 or >1, or with num_hidden_layers==1 combined with multiple draft layers.","commonSituations":"Using a multi-layer MTP draft checkpoint with a runtime that supports only 1 draft layer; converting/merging checkpoints that add several nextn layers.","solutions":["Use a checkpoint with exactly one nextn layer","Set spec num_nextn_layers=1 (or disable speculative decoding to skip the nextn path)","Re-export the draft model containing only the first nextn layer"],"exampleFix":"# before\n--speculative-algorithm EAGLE --speculative-num-steps 3 (multi-layer draft)\n# after\nuse draft weights with num_nextn_layers = 1","handlingStrategy":"validation","validationCode":"n = draft_cfg.get('spec',{}).get('num_nextn_layers', 0)\nif n: assert n == 1, f\"num_nextn_layers={n}, only 1 supported\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify draft checkpoint spec fields before enabling speculative decoding","Keep draft and target models version-aligned"],"tags":["speculative-decoding","mtp","checkpoint-loading"],"backgroundTag":"unsupported-draft-layer-count","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}