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 ClientNats.unwrap() when this.natsClient is null — the NATS connection has not been established. unwrap() returns the raw nats.Client for native subscription/JetStream access; connect() is what creates and stores natsClient. Calling unwrap() beforehand is an error because there is no underlying connection to expose.

Source

Thrown at packages/microservices/client/client-nats.ts:159

        default:
          this.logger.log(
            `NatsStatus: type: "${status.type}", data: "${data}".`,
          );
          break;
      }
    }
  }

  public on<
    EventKey extends keyof NatsEvents = keyof NatsEvents,
    EventCallback extends NatsEvents[EventKey] = NatsEvents[EventKey],
  >(event: EventKey, callback: EventCallback) {
    this.statusEventEmitter.on(event as string | symbol, callback as any);
  }

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

  public createSubscriptionHandler(
    packet: ReadPacket & PacketId,
    callback: (packet: WritePacket) => any,
  ) {
    return async (error: string | Error | undefined, natsMsg: NatsMsg) => {
      if (error) {
        return callback({
          err: error,
        });
      }
      const rawPacket = natsMsg.data;
      if (rawPacket?.length === 0) {

View on GitHub (pinned to 6ec0e2783d)

Solutions

1. Await client.connect() before client.unwrap().
2. Drive connect() from OnModuleInit (await it) so unwrap() in later handlers is safe.
3. After close(), construct a fresh ClientNats rather than unwrap()-ing the torn-down instance.
4. Gate unwrap() on the status Observable emitting NatsStatus.CONNECTED.

Example fix

// before
const client = new ClientNats({ options: {...} });
const nats = client.unwrap(); // throws

// after
await client.connect();
const nats = client.unwrap<Client>();

async function getNats(client: ClientNats) {
  await client.connect();
  return client.unwrap();
}

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

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. Using unwrap() in a constructor or OnModuleInit that runs before the async connect() finishes. Reusing a client after close() has cleared the reference.

Common situations: Calling native NATS APIs (nats.subscribe, JetStream management) too early in the NestJS lifecycle. Manual lifecycle management where connect() is invoked conditionally or after a delay. Race between application bootstrap and a request that needs the raw client.

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/f6e8339073d8d5cf.json. Report an issue: GitHub.