socketio/socket.io · error · Error

Illegal attachments

Error message

Illegal attachments

What it means

Thrown by decodeString() when parsing the attachments count of a BINARY_EVENT/BINARY_ACK packet: the substring between the type byte and the '-' delimiter is not a valid integer, or the delimiter '-' is missing. The encoded format is '<type><attachments>-<rest>'; a malformed attachments field triggers this.

Source

Thrown at packages/socket.io-parser/lib/index.ts:240

    // look up type
    const p: any = {
      type: Number(str.charAt(0)),
    };

    if (PacketType[p.type] === undefined) {
      throw new Error("unknown packet type " + p.type);
    }

    // look up attachments if type binary
    if (
      p.type === PacketType.BINARY_EVENT ||
      p.type === PacketType.BINARY_ACK
    ) {
      const start = i + 1;
      while (str.charAt(++i) !== "-" && i != str.length) {}
      const buf = str.substring(start, i);
      if (buf != Number(buf) || str.charAt(i) !== "-") {
        throw new Error("Illegal attachments");
      }
      const n = Number(buf);
      if (!isInteger(n) || n < 1) {
        throw new Error("Illegal attachments");
      } else if (n > this.opts.maxAttachments) {
        throw new Error("too many attachments");
      }
      p.attachments = n;
    }

    // look up namespace (if any)
    if ("/" === str.charAt(i + 1)) {
      const start = i + 1;
      while (++i) {
        const c = str.charAt(i);
        if ("," === c) break;
        if (i === str.length) break;
      }

View on GitHub (pinned to ae7fb46e08)

Solutions

1. Always emit binary events through the Encoder so the '<type><count>-...' format is generated correctly.
2. If hand-encoding, ensure the attachments count is a positive integer followed by '-'.
3. Validate/drop frames at the transport layer that do not match the binary-packet shape before decoding.

Example fix

// before (hand-built, malformed)
const frame = '5' + count + rest; // missing '-' -> throws

// after
const frame = '5' + count + '-' + rest;

function validBinaryHeader(s){
  const m = s.match(/^[56](\d+)-/);
  return !!m;
}

function hasWellFormedAttachments(s){ return /^[56]\d+-/.test(s); }

try { decoder.add(s); }
catch(e){ if(/Illegal attachments/.test(e.message)) return; throw e; }

When it happens

Trigger: A binary packet string like '5x-' (non-numeric attachments) or '5abc' (missing '-') causes `buf != Number(buf)` or `str.charAt(i) !== '-'` to be true.

Common situations: Corrupted/truncated frames; a producer that builds binary packet strings by hand and forgets the trailing '-' or inserts non-digits; protocol version skew.

Related errors

• illegal attachments
• got plaintext data when reconstructing a packet
• got binary data when not reconstructing a packet
• too many attachments
• unknown event name: ${eventName}

AI-assisted analysis of socketio/socket.io@ae7fb46e08 (2026-08-03). Data as JSON: /data/errors/5127fa9d129f90e1.json. Report an issue: GitHub.