{"id":"53ac34ff1f15cd20","repo":"socketio/socket.io","slug":"illegal-attachments","errorCode":null,"errorMessage":"illegal attachments","messagePattern":"illegal attachments","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/socket.io-parser/lib/binary.ts","lineNumber":74,"sourceCode":"\nexport function reconstructPacket(packet, buffers) {\n  packet.data = _reconstructPacket(packet.data, buffers);\n  delete packet.attachments; // no longer useful\n  return packet;\n}\n\nfunction _reconstructPacket(data, buffers) {\n  if (!data) return data;\n\n  if (data && data._placeholder === true) {\n    const isIndexValid =\n      typeof data.num === \"number\" &&\n      data.num >= 0 &&\n      data.num < buffers.length;\n    if (isIndexValid) {\n      return buffers[data.num]; // appropriate buffer (should be natural order anyway)\n    } else {\n      throw new Error(\"illegal attachments\");\n    }\n  } else if (Array.isArray(data)) {\n    for (let i = 0; i < data.length; i++) {\n      data[i] = _reconstructPacket(data[i], buffers);\n    }\n  } else if (typeof data === \"object\") {\n    for (const key in data) {\n      if (Object.prototype.hasOwnProperty.call(data, key)) {\n        data[key] = _reconstructPacket(data[key], buffers);\n      }\n    }\n  }\n\n  return data;\n}\n","sourceCodeStart":56,"sourceCodeEnd":90,"githubUrl":"https://github.com/socketio/socket.io/blob/ae7fb46e08c5ed964b4a1ea8b1703e816511598e/packages/socket.io-parser/lib/binary.ts#L56-L90","documentation":"Thrown by reconstructPacket/_reconstructPacket in the parser's binary module when a placeholder object's num field is not a valid index into the buffers array (it is not a number, is negative, or is >= buffers.length). During binary packet reconstruction each {_placeholder:true,num:N} marker is replaced by buffers[N]; an out-of-range N means the buffers and placeholders are out of sync.","triggerScenarios":"Reconstructing a binary packet whose placeholder references a buffer index that was never received, or where fewer binary attachments were supplied than the packet declared. Also triggered by hand-crafted/corrupted packets with bogus num values.","commonSituations":"A network/proxy dropping one of the binary attachment frames between the BINARY_EVENT header and the final buffer; a custom adapter that reorders or drops buffers; or a version mismatch between encoder and decoder that changes the placeholder format.","solutions":["Ensure the transport/adapter reliably delivers every binary attachment in order before reconstructPacket is called.","If you construct packets manually, verify every {_placeholder:true,num} references a valid index (0 <= num < buffers.length).","Upgrade encoder and decoder together so the placeholder/buffer contract matches."],"exampleFix":"// before\nconst packet = reconstructPacket(rawPacket, partialBuffers); // throws if num out of range\n\n// after\nconst expected = rawPacket.attachments || 0;\nif (partialBuffers.length < expected) {\n  throw new Error(`missing ${expected - partialBuffers.length} binary attachments`);\n}\nconst packet = reconstructPacket(rawPacket, partialBuffers);","handlingStrategy":"validation","validationCode":"function placeholdersOk(packet, buffers){\n  let ok=true;\n  (function walk(d){\n    if(d && d._placeholder===true){ if(!(typeof d.num==='number'&&d.num>=0&&d.num<buffers.length)) ok=false; return; }\n    if(Array.isArray(d)) d.forEach(walk); else if(d&&typeof d==='object') Object.keys(d).forEach(k=>walk(d[k]));\n  })(packet.data);\n  return ok;\n}","typeGuard":"function hasAllAttachments(packet, buffers){\n  return (packet.attachments||0) <= buffers.length;\n}","tryCatchPattern":"if(!placeholdersOk(rawPacket, buffers)){ throw new Error('illegal attachments: missing buffers'); }\nconst packet = reconstructPacket(rawPacket, buffers);","preventionTips":["Verify buffers.length >= declared attachments before reconstructing.","Use a reliable transport/adapter that preserves binary frame order.","Keep encoder and decoder on the same protocol version."],"tags":["parser","binary","attachments","reconstruction"],"analyzedSha":"ae7fb46e08c5ed964b4a1ea8b1703e816511598e","analyzedAt":"2026-08-03T19:08:14.127Z","schemaVersion":2}