nestjs/nest · error · Error

"unwrap" method not supported by the underlying server

Error message

"unwrap" method not supported by the underlying server

What it means

Thrown by NestMicroservice.unwrap() when the underlying serverInstance does not have an 'unwrap' method (the runtime checks "unwrap" in this.serverInstance). unwrap() is meant to expose the raw broker/server object; not every Server implements it (ServerGrpc.unwrap() throws its own gRPC-specific message; some custom servers omit it). The generic wrapper rejects the call when delegation is impossible.

Source

Thrown at packages/microservices/nest-microservice.ts:345

   * @param event Event name
   * @param callback Callback to be executed when the event is emitted
   */
  public on(event: string | number | symbol, callback: Function) {
    if ('on' in this.serverInstance) {
      return this.serverInstance.on(event as string, callback);
    }
    throw new Error('"on" method not supported by the underlying server');
  }

  /**
   * Returns an instance of the underlying server/broker instance,
   * or a group of servers if there are more than one.
   */
  public unwrap<T>(): T {
    if ('unwrap' in this.serverInstance) {
      return this.serverInstance.unwrap();
    }
    throw new Error('"unwrap" method not supported by the underlying server');
  }

  protected async closeApplication(): Promise<any> {
    this.socketModule && (await this.socketModule.close());
    this.microservicesModule && (await this.microservicesModule.close());

    await super.close();
    this.setIsTerminated(true);
  }

  protected async dispose(): Promise<void> {
    if (this.isTerminated) {
      return;
    }
    await this.serverInstance.close();
    this.socketModule && (await this.socketModule.close());
    this.microservicesModule && (await this.microservicesModule.close());
  }

View on GitHub (pinned to 6ec0e2783d)

Solutions

  1. Use a transport whose Server implements unwrap() (TCP/Redis/RMQ/MQTT/NATS) if you need the raw driver.
  2. Add an unwrap() method to your custom Server subclass returning the underlying handle.
  3. For gRPC, do not call unwrap() — access the gRPC client/services via the service client instead.

Example fix

// before
const app = await NestFactory.createMicroservice(AppModule, { transport: Transport.GRPC, options: {...} });
const raw = app.unwrap(); // throws

// after
// gRPC does not expose unwrap(); obtain the typed service client instead
const svc = app.get('UserService');
Defensive patterns

Strategy: type-guard

Validate before calling

function supportsUnwrap(server: any): boolean {
  return server && 'unwrap' in server && typeof server.unwrap === 'function'
    && !/GRPC/.test(server.constructor?.name);
}
if (supportsUnwrap(server)) server.unwrap();
else { /* obtain service client instead */ }

Type guard

import { ServerGrpc } from '@nestjs/microservices';
const supportsServerUnwrap = (s: any): boolean => !(s instanceof ServerGrpc) && 'unwrap' in s;

Try / catch

try {
  return app.unwrap();
} catch (e) {
  if (/"unwrap" method not supported/.test(e?.message)) { /* use service client instead */ }
  else throw e;
}

Prevention

When it happens

Trigger: Calling app.unwrap() on a NestMicroservice backed by a gRPC server or a custom Server that does not define unwrap(). Generic code that assumes every server exposes its raw driver via unwrap().

Common situations: Hybrid apps with a gRPC server where bootstrap code calls unwrap() to grab the raw driver. Custom Server subclass authored without unwrap().

Related errors

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