nestjs/nest · error · Error

Not initialized. Please call the "listen"/"startAllMicroserv

Error message

Not initialized. Please call the "listen"/"startAllMicroservices" method before accessing the server.

What it means

Error "Not initialized. Please call the "listen"/"startAllMicroservices" method before accessing the server." thrown in nestjs/nest.

Source

Thrown at packages/microservices/server/server-tcp.ts:154

  public handleClose(): undefined | number | NodeJS.Timer {
    if (
      this.isManuallyTerminated ||
      !this.getOptionsProp(this.options, 'retryAttempts') ||
      this.retryAttemptsCount >=
        this.getOptionsProp(this.options, 'retryAttempts', 0)
    ) {
      return undefined;
    }
    ++this.retryAttemptsCount;
    return setTimeout(
      () => this.server.listen(this.port, this.host),
      this.getOptionsProp(this.options, 'retryDelay', 0),
    );
  }

  public unwrap<T>(): T {
    if (!this.server) {
      throw new Error(
        'Not initialized. Please call the "listen"/"startAllMicroservices" method before accessing the server.',
      );
    }
    return this.server as T;
  }

  public on<
    EventKey extends keyof TcpEvents = keyof TcpEvents,
    EventCallback extends TcpEvents[EventKey] = TcpEvents[EventKey],
  >(event: EventKey, callback: EventCallback) {
    if (this.server) {
      this.server.on(event, callback as any);
    } else {
      this.pendingEventListeners.push({ event, callback });
    }
  }

  protected init() {

View on GitHub (pinned to 6ec0e2783d)

Solutions

1. Call app.listen() or app.startAllMicroservices() before accessing the TCP server instance.
2. Await listen() so the underlying socket server is bound before any access.

Example fix

const app = await NestFactory.createMicroservice(AppModule, opts);
await app.listen();
const server = app.get(ServerTCP);

When it happens

Trigger: Thrown at packages/microservices/server/server-tcp.ts:154 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/17b8077b92132f38.json. Report an issue: GitHub.