{"record":{"id":"86f44c5fccbab541","repo":"sgl-project/sglang","slug":"eagle3-currently-only-supports-1-layer","errorCode":null,"errorMessage":"EAGLE3 currently only supports 1 layer","messagePattern":"EAGLE3 currently only supports 1 layer","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/models/kimi_k25_eagle3.py","lineNumber":243,"sourceCode":"        )\n\n        # Per-aux RMSNorm before fc; enabled via `fc_norm` or legacy\n        # `use_aux_norm` flag. Matches the eagle3.1 layout.\n        use_fc_norm = getattr(config, \"fc_norm\", None) or getattr(\n            config, \"use_aux_norm\", False\n        )\n        if use_fc_norm:\n            self.fc_norm = nn.ModuleList(\n                [\n                    RMSNorm(target_hidden_size, eps=config.rms_norm_eps)\n                    for _ in range(self.num_aux_hidden_states)\n                ]\n            )\n        else:\n            self.fc_norm = None\n\n        if config.num_hidden_layers != 1:\n            raise ValueError(\"EAGLE3 currently only supports 1 layer\")\n        self.midlayer = Eagle3MLADecoderLayer(\n            config,\n            layer_id=0,\n            quant_config=quant_config,\n            prefix=prefix,\n        )\n\n        self.norm = RMSNorm(config.hidden_size, eps=config.rms_norm_eps)\n        # Draft decode captures pre-norm hidden by default; eagle3.1 opts for\n        # post-norm via `norm_output: true`.\n        self.norm_output = getattr(config, \"norm_output\", False)\n\n    def forward(\n        self,\n        input_ids: torch.Tensor,\n        positions: torch.Tensor,\n        forward_batch: ForwardBatch,\n        input_embeds: torch.Tensor = None,","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/models/kimi_k25_eagle3.py#L225-L261","documentation":"The EAGLE3 draft model for Kimi K2.5 is hardcoded to exactly one decoder layer (the single midlayer built at layer_id=0). The EAGLE3 paper's feature-extraction draft uses one layer, so multi-layer draft configs are rejected up front with this ValueError rather than silently mis-loading weights.","triggerScenarios":"Loading an EAGLE3 draft model whose config.json has num_hidden_layers != 1 (e.g. 2 or more) — the model builds a single Eagle3MLADecoderLayer and there is no code path for additional layers.","commonSituations":"Using a community EAGLE3 draft checkpoint with extra layers; editing a draft config and bumping num_hidden_layers; accidentally passing a full model (many layers) as --speculative-draft-model-path.","solutions":["Set num_hidden_layers to 1 in the EAGLE3 draft model's config.json.","Use an official/validated single-layer EAGLE3 draft checkpoint for Kimi K2.5.","If multi-layer drafting is needed, use the standard EAGLE (non-EAGLE3) draft path which supports multiple layers."],"exampleFix":"// before (draft config.json)\n{\"num_hidden_layers\": 4, ...}\n\n// after\n{\"num_hidden_layers\": 1, ...}","handlingStrategy":"validation","validationCode":"assert json.load(open(draft_config_path))[\"num_hidden_layers\"] == 1, \"EAGLE3 draft must have exactly 1 layer\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pre-flight check num_hidden_layers==1 for EAGLE3 drafts.","Keep full-depth models as target, not draft, in speculative configs."],"tags":["eagle3","speculative-decoding","config-validation","kimi"],"backgroundTag":"model-config-invalid-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}