What causes "unknown event name: ${eventName}" in socketio/socket.io?

Add a case branch in pack() for each event name your app emits, mapping it to a schemapack schema.

socketio/socket.io · error · Error

unknown event name: ${eventName}

Error message

unknown event name: ${eventName}

What it means

Thrown by the custom-parser example's Encoder.pack() when the first element of packet.data (the event name) does not match any of the three hard-coded schema names ('string', 'numeric', 'binary'). This example uses schemapack to map specific event names to specific binary schemas, so any event name outside that whitelist has no encoder.

Source

Thrown at examples/custom-parsers/src/custom-parser.js:68

  }
  pack (packet) {
    let eventName = packet.data[0];
    let flatPacket = {
      data: packet.data[1],
      nsp: packet.nsp
    };
    switch (eventName) {
      case 'string':
        flatPacket._id = 1;
        return stringSchema.encode(flatPacket);
      case 'numeric':
        flatPacket._id = 2;
        return numericSchema.encode(flatPacket);
      case 'binary':
        flatPacket._id = 3;
        return binarySchema.encode(flatPacket);
      default:
        throw new Error('unknown event name: ' + eventName);
    }
  }
}

class Decoder extends Emitter {
  add (obj) {
    if (typeof obj === 'string') {
      this.parseJSON(obj);
    } else {
      this.parseBinary(obj);
    }
  }
  parseJSON (obj) {
    try {
      let decoded = JSON.parse(obj);
      this.emit('decoded', decoded);
    } catch (e) {
      this.emit('decoded', errorPacket);

View on GitHub (pinned to ae7fb46e08)

Solutions

Add a case branch in pack() for each event name your app emits, mapping it to a schemapack schema.
If you want a generic fallback, add a default branch that JSON-stringifies the packet instead of throwing.
Restrict your application's emit() calls to the event names defined in the switch statement.

Example fix

// before
switch (eventName) {
  case 'string': ... // no default -> throws
}

// after
switch (eventName) {
  case 'string': ... 
  case 'numeric': ... 
  case 'binary': ... 
  case 'hello':
    flatPacket._id = 4;
    return helloSchema.encode(flatPacket);
  default:
    throw new Error('unknown event name: ' + eventName);
}

Defensive patterns

Strategy: validation

Validate before calling

const KNOWN = new Set(['string','numeric','binary']);
function canEncode(eventName){ return KNOWN.has(eventName); }

Type guard

function isKnownEvent(name){ return ['string','numeric','binary'].includes(name); }

Try / catch

if(!isKnownEvent(packet.data[0])){ throw new Error('unknown event name: '+packet.data[0]); }

Prevention

Register a schema branch in pack() for every event name your app emits.
Add a generic JSON fallback default branch instead of throwing.
Keep an allow-list of event names and validate before emitting.

When it happens

Trigger: Calling the custom Encoder with an EVENT packet whose data[0] is anything other than the literal strings 'string', 'numeric', or 'binary' (e.g. socket.emit('hello') through this parser).

Common situations: Adapting the custom-parser example to a real app but forgetting to add new schema branches for the app's actual event names; or emitting a reserved/system event through the custom parser.

Related errors

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