socketio/socket.io · error · Error

"${String(ev)}" is a reserved event name

Error message

"${String(ev)}" is a reserved event name

What it means

Thrown by Namespace.serverSideEmit() when the event name is in the namespace's RESERVED_EVENTS set (connect, connection, new_namespace, defined at namespace.ts:64). serverSideEmit forwards events to other Socket.IO servers in the cluster; the reserved names are used for namespace lifecycle and would collide with internal multi-server coordination if user-emit.

Source

Thrown at packages/socket.io/lib/namespace.ts:544

   *   }
   * });
   *
   * myNamespace.on("ping", (cb) => {
   *   cb("pong");
   * });
   *
   * @param ev - the event name
   * @param args - an array of arguments, which may include an acknowledgement callback at the end
   */
  public serverSideEmit<Ev extends EventNames<ServerSideEvents>>(
    ev: Ev,
    ...args: EventParams<
      DecorateAcknowledgementsWithTimeoutAndMultipleResponses<ServerSideEvents>,
      Ev
    >
  ): boolean {
    if (RESERVED_EVENTS.has(ev)) {
      throw new Error(`"${String(ev)}" is a reserved event name`);
    }
    args.unshift(ev);
    this.adapter.serverSideEmit(args);
    return true;
  }

  /**
   * Sends a message and expect an acknowledgement from the other Socket.IO servers of the cluster.
   *
   * @example
   * const myNamespace = io.of("/my-namespace");
   *
   * try {
   *   const responses = await myNamespace.serverSideEmitWithAck("ping");
   *   console.log(responses); // one response per server (except the current one)
   * } catch (e) {
   *   // some servers did not acknowledge the event in the given delay
   * }

View on GitHub (pinned to ae7fb46e08)

Solutions

1. Rename the server-to-server event to a non-reserved name (e.g. 'peer:connected').
2. Remember the namespace reserved set is {connect, connection, new_namespace} (note 'connection' — distinct from the socket-level reserved list).
3. Validate dynamic event names against this set before calling serverSideEmit.

Example fix

// before
io.of('/admin').serverSideEmit('connection', info);

// after
io.of('/admin').serverSideEmit('peer:joined', info);

const NS_RESERVED = new Set(['connect','connection','new_namespace']);
function assertNotReserved(ev){ if(NS_RESERVED.has(ev)) throw new Error(ev+' is reserved'); }

function isServerSideEmittable(ev){ return !['connect','connection','new_namespace'].includes(ev); }

When it happens

Trigger: Calling io.of('/ns').serverSideEmit('connect'), serverSideEmit('connection'), or serverSideEmit('new_namespace').

Common situations: Using serverSideEmit to broadcast a 'connection' notification to peer servers; reusing namespace lifecycle event names for custom cluster messages; or confusion with socket.emit reserved events (different set).

Related errors

• "${String(ev)}" is a reserved event name
• No adapter for this namespace, are you trying to get the lis
• "${ev.toString()}" is a reserved event name
• "${String(ev)}" is a reserved event name
• Acknowledgements are not supported

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