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 ClientMqtt.unwrap() when this.mqttClient is null, i.e. the underlying mqtt.MqttClient has not been created yet. unwrap() exists to hand back the raw broker client so you can call native MQTT APIs; before connect() runs there is no native client to return, so the call is rejected. connect() creates mqttClient, registers the CONNECT listener, and flips the connectionPromise to resolved.

Source

Thrown at packages/microservices/client/client-mqtt.ts:189

        client.on('message', this.createResponseCallback());
      }
    });
  }

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

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

  public createResponseCallback(): (channel: string, buffer: Buffer) => any {
    return async (channel: string, buffer: Buffer) => {
      const packet = JSON.parse(buffer.toString());
      const { err, response, isDisposed, id } =
        await this.deserializer.deserialize(packet);

      const callback = this.routingMap.get(id);
      if (!callback) {
        return undefined;
      }
      if (isDisposed || err) {
        return callback({

View on GitHub (pinned to 6ec0e2783d)

Solutions

1. Call and await client.connect() before client.unwrap().
2. If using ClientsModule, await the client.connect() in onModuleInit (or rely on the first emit/send which triggers connect) before unwrap().
3. After close(), create a new ClientMqtt instance rather than calling unwrap() on the closed one.
4. Type-narrow before calling: check via the connectionPromise / status Observable.

Example fix

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

// after
await client.connect();
const mqtt = client.unwrap<MqttClient>();

// Ensure connect() has run before unwrap()
async function getMqtt(client: ClientMqtt) {
  await client.connect();
  return client.unwrap();
}

import { ClientMqtt } from '@nestjs/microservices';
import type { MqttClient } from 'mqtt';
const isMqttClient = (c: unknown): c is ClientMqtt => c instanceof ClientMqtt;
function isReady(c: ClientMqtt): boolean { return !!(c as any).mqttClient; }

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() (or before the connect() promise resolves). Calling unwrap() after close() has nulled the client. Constructing a ClientMqtt via ClientsModule and immediately calling unwrap() in onModuleInit before awaiting connect().

Common situations: DI lifecycle misuse: using unwrap() in OnModuleInit without first awaiting connect() (NestJS does connect lazily, so the first send() triggers it, but unwrap() does not). Calling close() then unwrap() for a reconnect routine. Hot-restart scenarios where the client reference is reused after teardown.

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