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

`ClientKafka.unwrap()` throws when `this.client` (the native kafkajs `Kafka` instance) is null, i.e. before `connect()` has been called. Once connected, `unwrap()` returns the underlying kafkajs instance for advanced use cases not covered by the NestJS wrapper.

Source

Thrown at packages/microservices/client/client-kafka.ts:285

      resetOnDisconnect: false,
    });
    connectableSource.connect();
    return connectableSource;
  }

  public commitOffsets(
    topicPartitions: TopicPartitionOffsetAndMetadata[],
  ): Promise<void> {
    if (this._consumer) {
      return this._consumer.commitOffsets(topicPartitions);
    } else {
      throw new Error('No consumer initialized');
    }
  }

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

  public on<
    EventKey extends string | number | symbol = string | number | symbol,
    EventCallback = any,
  >(event: EventKey, callback: EventCallback) {
    throw new Error('Method is not supported for Kafka client');
  }

  protected registerConsumerEventListeners() {
    if (!this._consumer) {
      return;
    }
    this._consumer.on(this._consumer.events.CONNECT, () =>

View on GitHub (pinned to 6ec0e2783d)

Solutions

Await `connect()` before calling `unwrap()`.
Cache the result of `unwrap()` after connect if you need it repeatedly.
Prefer the wrapped APIs (`subscribeToResponseOf`, `emit`, `send`) when possible.

Example fix

// before
const kafka = this.client.unwrap(); // throws
// after
async onModuleInit() {
  await this.client.connect();
  const kafka = this.client.unwrap();
  const admin = kafka.admin();
}

Defensive patterns

Strategy: validation

Validate before calling

// Connect before unwrapping the native kafkajs client
await this.client.connect();
const kafka = this.client.unwrap();

Type guard

function hasKafkaClient(c: ClientKafka): boolean { return Reflect.get(c, 'client') != null; }

Try / catch

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

Prevention

Await `connect()` before calling `unwrap()`.
Cache the unwrapped instance after connect if used repeatedly.
Prefer the wrapped APIs unless you need kafkajs-specific features.

When it happens

Trigger: Calling `clientKafka.unwrap()` before `connect()` has run (e.g. synchronously right after construction, or in `onModuleInit` before the connect await).

Common situations: Needing the raw kafkajs `Kafka`/admin/producer object for advanced APIs; calling unwrap too early in the lifecycle; after `close()` reset the client to null.

Related errors

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