nestjs/nest · error · InvalidSocketPortException

Invalid port (${port}) in gateway ${type}

Error message

Invalid port (${port}) in gateway ${type}

What it means

Error "Invalid port (${port}) in gateway ${type}" thrown in nestjs/nest.

Source

Thrown at packages/websockets/web-sockets-controller.ts:55

  constructor(
    private readonly socketServerProvider: SocketServerProvider,
    private readonly config: ApplicationConfig,
    private readonly contextCreator: WsContextCreator,
    private readonly graphInspector: GraphInspector,
    private readonly appOptions: NestApplicationContextOptions = {},
  ) {}

  public connectGatewayToServer(
    instance: NestGateway,
    metatype: Type<unknown> | Function,
    moduleKey: string,
    instanceWrapperId: string,
  ) {
    const options = Reflect.getMetadata(GATEWAY_OPTIONS, metatype) || {};
    const port = Reflect.getMetadata(PORT_METADATA, metatype) || 0;

    if (!Number.isInteger(port)) {
      throw new InvalidSocketPortException(port, metatype);
    }
    this.subscribeToServerEvents(
      instance,
      options,
      port,
      moduleKey,
      instanceWrapperId,
    );
  }

  public subscribeToServerEvents<T extends GatewayMetadata>(
    instance: NestGateway,
    options: T,
    port: number,
    moduleKey: string,
    instanceWrapperId: string,
  ) {
    const nativeMessageHandlers = this.metadataExplorer.explore(instance);

View on GitHub (pinned to 6ec0e2783d)

Solutions

1. Provide a valid port number (0-65535) in @WebSocketGateway(port) or in the gateway options.
2. Remove the port option to use the default HTTP server port instead of an invalid value.
3. Ensure the port value is a number, not a string or undefined variable.

Example fix

@WebSocketGateway(3001, { namespace: 'events' })
export class EventsGateway {}

When it happens

Trigger: Thrown at packages/websockets/web-sockets-controller.ts:55 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nestjs/nest@6ec0e2783d (2026-08-03). Data as JSON: /data/errors/88c66a6d8745ff13.json. Report an issue: GitHub.