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 ClientRMQ.unwrap() when this.client is null. this.client is the amqp-connection-manager (AmqpConnectionManager) created during connect(). unwrap() exposes it for native AMQP channel/assertion APIs; before connect() runs there is no connection manager to expose.

Source

Thrown at packages/microservices/client/client-rmq.ts:328

      this._status$.next(RmqStatus.UNBLOCKED);
      this.logger.log(UNBLOCKED_RMQ_MESSAGE);
    });
  }

  public on<
    EventKey extends keyof RmqEvents = keyof RmqEvents,
    EventCallback extends RmqEvents[EventKey] = RmqEvents[EventKey],
  >(event: EventKey, callback: EventCallback) {
    if (this.client) {
      this.client.addListener(event, callback);
    } else {
      this.pendingEventListeners.push({ event, callback });
    }
  }

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

  public async handleMessage(
    packet: unknown,
    callback: (packet: WritePacket) => any,
  ): Promise<void>;
  public async handleMessage(
    packet: unknown,
    options: Record<string, unknown>,
    callback: (packet: WritePacket) => any,
  ): Promise<void>;
  public async handleMessage(
    packet: unknown,
    options:

View on GitHub (pinned to 6ec0e2783d)

Solutions

Await client.connect() before client.unwrap().
Confirm the RabbitMQ broker URL, vhost, and credentials allow the connection to complete.
After close(), create a new ClientRMQ rather than unwrap()-ing the closed instance.
Gate unwrap() on the status Observable (RmqStatus.CONNECTED).

Example fix

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

// after
await client.connect();
const conn = client.unwrap<AmqpConnectionManager>();

Defensive patterns

Strategy: validation

Validate before calling

async function getRmq(client: ClientRMQ) {
  await client.connect();
  return client.unwrap();
}

Type guard

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

Try / catch

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

Prevention

Await connect() before unwrap().
Confirm RabbitMQ URL/vhost/credentials are valid so connect() completes.
Recreate the client after close().

When it happens

Trigger: Calling client.unwrap() before client.connect() resolves. Calling unwrap() after close() which clears the connection manager. onModuleInit ordering where unwrap() is invoked before the RabbitMQ connection promise settles.

Common situations: Asserting queues/exchanges via the raw connection manager before connect() finished. Reconnect routines that close() then unwrap(). RabbitMQ broker unreachable at startup so connect() never completes, but unwrap() is still called downstream.

Related errors

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