socketio/socket.io · error · Error

got binary data when not reconstructing a packet

Error message

got binary data when not reconstructing a packet

What it means

Thrown by the parser Decoder.add() when a binary blob/buffer arrives but no BinaryReconstructor is active (this.reconstructor is null). Binary data is only meaningful while reconstructing a previously announced BINARY_EVENT/BINARY_ACK packet; unsolicited binary frames violate the protocol.

Source

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

    let packet;
    if (typeof obj === "string") {
      if (this.reconstructor) {
        throw new Error("got plaintext data when reconstructing a packet");
      }
      packet = this.decodeString(obj);
      const isBinaryEvent = packet.type === PacketType.BINARY_EVENT;
      if (isBinaryEvent || packet.type === PacketType.BINARY_ACK) {
        packet.type = isBinaryEvent ? PacketType.EVENT : PacketType.ACK;
        // binary packet's json
        this.reconstructor = new BinaryReconstructor(packet);
      } else {
        // non-binary full packet
        super.emitReserved("decoded", packet);
      }
    } else if (isBinary(obj) || obj.base64) {
      // raw binary data
      if (!this.reconstructor) {
        throw new Error("got binary data when not reconstructing a packet");
      } else {
        packet = this.reconstructor.takeBinaryData(obj);
        if (packet) {
          // received final buffer
          this.reconstructor = null;
          super.emitReserved("decoded", packet);
        }
      }
    } else {
      throw new Error("Unknown type: " + obj);
    }
  }

  /**
   * Decode a packet String (JSON data)
   *
   * @param {String} str
   * @return {Object} packet

View on GitHub (pinned to ae7fb46e08)

Solutions

1. Confirm the server is emitting events with binary content via the Socket.IO parser so it always sends a BINARY_EVENT header first.
2. Make sure a string BINARY_EVENT packet is fed to add() before any binary buffers.
3. Filter out non-Socket.IO binary frames at the transport layer before they reach the decoder.

Example fix

// before
decoder.add(arrayBuffer); // throws: no reconstructor

// after
// first emit/forward the BINARY_EVENT string packet that declares the attachments
decoder.add(binaryEventString); // initializes reconstructor
decoder.add(arrayBuffer); // now valid

function canAcceptBinary(decoder){ return !!decoder.reconstructor; }

function isBinaryFrame(obj){ return obj instanceof ArrayBuffer || Buffer.isBuffer(obj) || obj instanceof Blob || (obj&&obj.base64); }

try { decoder.add(buf); }
catch(e){ if(/binary data when not reconstructing/.test(e.message)) return; else throw e; }

When it happens

Trigger: Calling decoder.add(someArrayBuffer) (or any isBinary/base64 object) before any BINARY_EVENT/BINARY_ACK string packet has initialized a reconstructor.

Common situations: A transport that sends binary WebSocket frames outside the Socket.IO binary-attachment handshake (e.g. raw ping/pong data, or a misconfigured engine.io); or feeding test fixtures binary data without a preceding binary packet header.

Related errors

• got plaintext data when reconstructing a packet
• unknown packet type ${p.type}
• Illegal attachments
• unknown event name: ${eventName}
• illegal attachments

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