{"record":{"id":"4af3f8d63788755d","repo":"sgl-project/sglang","slug":"missing-aux-index-for-last-chunk","errorCode":null,"errorMessage":"Missing aux index for last chunk","messagePattern":"Missing aux index for last chunk","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/nixl/conn.py","lineNumber":1284,"sourceCode":"                            state_xfer_handles = self.maybe_send_extra(\n                                req.agent_name,\n                                kv_chunk.state_indices,\n                                dst_info.dst_state_data_ptrs,\n                                req.dst_state_indices,\n                                dst_info.gpu_id,\n                                f\"{req.room}_state_{self.transfer_source_rank}\",\n                                decode_tp_size,\n                                decode_tp_rank=dst_info.decode_tp_rank,\n                                dst_state_item_lens=dst_info.dst_state_item_lens,\n                                dst_state_dim_per_tensor=dst_info.dst_state_dim_per_tensor,\n                                dst_state_layer_ids=dst_info.dst_state_layer_ids,\n                            )\n                            handles.extend(\n                                h for h in state_xfer_handles if h is not None\n                            )\n\n                        if kv_chunk.prefill_aux_index is None:\n                            raise RuntimeError(\"Missing aux index for last chunk\")\n                        # A no-KV notification still identifies its PP source.\n                        # Empty non-final chunks do not consume chunk IDs, so a\n                        # final no-KV chunk_id equals the prior KV chunk count.\n                        aux_notif = f\"{req.room}_aux\"\n                        if (\n                            len(kv_chunk.prefill_kv_indices) == 0\n                            or not self.kv_args.kv_data_ptrs\n                        ):\n                            aux_notif += (\n                                f\"_nokv_{self.transfer_source_rank}\"\n                                f\"_{kv_chunk.chunk_id}\"\n                            )\n                        aux_xfer_handle = self.send_aux(\n                            req.agent_name,\n                            kv_chunk.prefill_aux_index,\n                            dst_info.dst_aux_ptrs,\n                            req.dst_aux_index,\n                            aux_notif,","sourceCodeStart":1266,"sourceCodeEnd":1302,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/nixl/conn.py#L1266-L1302","documentation":"On the last chunk of a transfer, transfer_worker requires kv_chunk.prefill_aux_index to send the aux tensor; if it is None it raises RuntimeError. The aux index is populated during prefill request processing, so a None value on the final chunk means the chunk descriptor was built incompletely — an internal invariant break rather than an expected condition.","triggerScenarios":"kv_chunk.is_last_chunk is True while kv_chunk.prefill_aux_index is None — happens if the chunk producer (prefill scheduler / KV chunker) failed to attach the aux index, or a custom/disaggregation bootstrap path constructs chunks without aux metadata.","commonSituations":"Bugs in chunked prefill or aux-tensor changes (e.g. a model/backend that does not allocate aux buffers, or a modified chunker); version mismatch between components that produce and consume chunk descriptors.","solutions":["Verify the model/backend supports the aux tensors the NIXL path expects (check kv_args.aux_data_ptrs is populated)","Check for and upgrade past SGLang versions with chunked-transfer aux-index bugs","Reproduce with a minimal PD setup and report with the room/chunk logs"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if chunk.is_last_chunk:\n    assert chunk.prefill_aux_index is not None, 'chunker bug: aux index missing on final chunk'","typeGuard":null,"tryCatchPattern":"except RuntimeError as e:\n    if 'Missing aux index' in str(e):\n        mark_request_failed_and_retry_prefill(room)","preventionTips":["Unit-test chunk producers so the last chunk always carries aux metadata","Keep chunk-producing and chunk-consuming components at the same version","Watch for this on custom backends that skip aux buffer allocation"],"tags":["nixl","disaggregation","chunked-transfer","internal-invariant"],"backgroundTag":"invalid-state-invariant-violation","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}