nestjs/nest · error · Error

Not initialized. Please call the "connect" method first.

Error message

Not initialized. Please call the "connect" method first.

What it means

Thrown by ClientTCP.unwrap() when this.socket is null. this.socket is the JsonSocket wrapper around the raw net.Socket, created by connect(). unwrap() returns the underlying netSocket (the raw TCP socket) so you can apply native socket options; before connect() there is no socket.

Source

Thrown at packages/microservices/client/client-tcp.ts:182

      }
      this.routingMap.clear();
    }
  }

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

  public unwrap<T>(): T {
    if (!this.socket) {
      throw new Error(
        'Not initialized. Please call the "connect" method first.',
      );
    }
    return this.socket.netSocket as T;
  }

  protected publish(
    partialPacket: ReadPacket,
    callback: (packet: WritePacket) => any,
  ): () => void {
    try {
      const packet = this.assignPacketId(partialPacket);
      const serializedPacket = this.serializer.serialize(packet);

      this.routingMap.set(packet.id, callback);
      this.socket!.sendMessage(serializedPacket);

      return () => this.routingMap.delete(packet.id);

View on GitHub (pinned to 6ec0e2783d)

Solutions

1. Await client.connect() before client.unwrap().
2. In reconnect handlers, re-await connect() before unwrap(); do not unwrap() right after handleClose.
3. Ensure the TCP microservice server host/port is reachable so connect() completes.
4. Gate unwrap() on the status Observable (TcpStatus.CONNECTED).

Example fix

// before
const client = new ClientTCP({ host: '127.0.0.1', port: 3001 });
const sock = client.unwrap(); // throws

// after
await client.connect();
const sock = client.unwrap<Socket>();
sock.setKeepAlive(true, 1000);

async function getSocket(client: ClientTCP) {
  await client.connect();
  return client.unwrap();
}

import { ClientTCP } from '@nestjs/microservices';
const isTcpClient = (c: unknown): c is ClientTCP => c instanceof ClientTCP;
function isReady(c: ClientTCP): boolean { return !!(c as any).socket; }

try {
  return client.unwrap();
} catch (e) {
  if (/Not initialized/.test(e?.message)) { await client.connect(); return client.unwrap(); }
  throw e;
}

When it happens

Trigger: Calling client.unwrap() before client.connect() resolves. Calling unwrap() after handleClose() which nulls this.socket and connectionPromise. Network drop followed by an unwrap() before reconnect completes.

Common situations: Setting socket options (setKeepAlive, setTimeout, setNoDelay) in onModuleInit before awaiting connect(). Reconnect/error handler logic that calls unwrap() on a client whose socket was just closed. TCP server not yet listening at startup so connect() fails and downstream unwrap() throws.

Related errors

• Not initialized. Please call the "connect" method first.
• Not initialized. Please call the "connect" method first.
• Not initialized. Please call the "connect" method first.
• Not initialized. Please call the "connect" method first.
• No consumer initialized. Please, call the "connect" method f

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