{"record":{"id":"c4df4d2f367d2144","repo":"can1357/oh-my-pi","slug":"rpc-chunk-sequence-must-start-at-index-0","errorCode":null,"errorMessage":"rpc chunk sequence must start at index 0","messagePattern":"rpc chunk sequence must start at index 0","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/modes/rpc/rpc-frame.ts","lineNumber":165,"sourceCode":"\t\t\ttypeof chunkId !== \"string\" ||\n\t\t\tchunkId.length === 0 ||\n\t\t\tchunkId.length > 128 ||\n\t\t\t!Number.isSafeInteger(index) ||\n\t\t\t!Number.isSafeInteger(count) ||\n\t\t\t!Number.isSafeInteger(byteLength) ||\n\t\t\tindex < 0 ||\n\t\t\tcount < 2 ||\n\t\t\tcount > Math.ceil(MAX_RPC_REASSEMBLED_BYTES / RPC_CHUNK_PAYLOAD_BYTES) ||\n\t\t\tindex >= count ||\n\t\t\tbyteLength < MAX_RPC_FRAME_BYTES ||\n\t\t\tbyteLength > MAX_RPC_REASSEMBLED_BYTES\n\t\t)\n\t\t\tthrow new Error(\"invalid rpc chunk metadata\");\n\t\tconst bytes = decodeBase64(value.data);\n\t\tif (bytes.byteLength > RPC_CHUNK_PAYLOAD_BYTES) throw new Error(\"rpc chunk payload exceeds the transport limit\");\n\n\t\tif (!this.#pending) {\n\t\t\tif (index !== 0) throw new Error(\"rpc chunk sequence must start at index 0\");\n\t\t\tthis.#pending = { chunkId, count, byteLength, nextIndex: 0, chunks: [], receivedBytes: 0 };\n\t\t}\n\t\tconst pending = this.#pending;\n\t\tif (\n\t\t\tpending.chunkId !== chunkId ||\n\t\t\tpending.count !== count ||\n\t\t\tpending.byteLength !== byteLength ||\n\t\t\tpending.nextIndex !== index\n\t\t)\n\t\t\tthrow new Error(\"rpc chunk sequence mismatch\");\n\t\tpending.chunks.push(bytes);\n\t\tpending.receivedBytes += bytes.byteLength;\n\t\tpending.nextIndex++;\n\t\tif (pending.receivedBytes > pending.byteLength) throw new Error(\"rpc chunk sequence exceeds declared length\");\n\t\tif (pending.nextIndex < pending.count) return undefined;\n\t\tif (pending.receivedBytes !== pending.byteLength) throw new Error(\"rpc chunk sequence length mismatch\");\n\n\t\tthis.#pending = undefined;","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/modes/rpc/rpc-frame.ts#L147-L183","documentation":"When no reassembly is in progress (#pending undefined), the first rpc_chunk received must carry index 0. This error is thrown when a decoder that has not seen any chunks receives a continuation chunk (index > 0), meaning the start of the chunked sequence was lost or skipped.","triggerScenarios":"Starting to read the stream mid-sequence (decoder created after the sender already emitted chunk 0); chunk 0 dropped by an intermediate transport; reusing a fresh decoder to replay a capture that begins mid-frame.","commonSituations":"Attaching to a long-running agent's RPC stream late (tail-follow); log rotation or pipe buffering that discarded early lines; resuming after an error without restarting the sequence.","solutions":["Consume the RPC stream from its beginning so chunk 0 of every sequence is seen.","On any sequence error, reset (recreate the decoder) and re-request the frame rather than continuing mid-sequence.","Ensure the transport is reliable (no line drops) between sender and decoder."],"exampleFix":"// before: late-attaching decoder to an in-flight stream\nconst decoder = new RpcFrameDecoder(); stream.pipe(lateHandler);\n// after: restart the stream so the sequence begins at index 0\nrestartStream(); // then pipe all lines from the start","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  const frame = decoder.push(parsedLine);\n} catch (err) {\n  if (err instanceof Error && err.message === \"rpc chunk sequence must start at index 0\") {\n    // stream was joined mid-sequence: restart the source and recreate the decoder\n    decoder = new RpcFrameDecoder();\n    restartStreamFromBeginning();\n  } else throw err;\n}","preventionTips":["Consume the stream from its start; never tail-join an RPC channel mid-frame.","Reset decoder state on reconnect.","Make the transport drop-free (pipes, not lossy logs)."],"tags":["rpc","protocol","stream-ordering","state"],"backgroundTag":"rpc-chunk-sequence-out-of-order","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}