{"id":"d75f819b562716b4","repo":"nestjs/nest","slug":"unwrap-method-not-supported-by-the-underlying-se","errorCode":null,"errorMessage":"\"unwrap\" method not supported by the underlying server","messagePattern":"\"unwrap\" method not supported by the underlying server","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/microservices/nest-microservice.ts","lineNumber":345,"sourceCode":"   * @param event Event name\n   * @param callback Callback to be executed when the event is emitted\n   */\n  public on(event: string | number | symbol, callback: Function) {\n    if ('on' in this.serverInstance) {\n      return this.serverInstance.on(event as string, callback);\n    }\n    throw new Error('\"on\" method not supported by the underlying server');\n  }\n\n  /**\n   * Returns an instance of the underlying server/broker instance,\n   * or a group of servers if there are more than one.\n   */\n  public unwrap<T>(): T {\n    if ('unwrap' in this.serverInstance) {\n      return this.serverInstance.unwrap();\n    }\n    throw new Error('\"unwrap\" method not supported by the underlying server');\n  }\n\n  protected async closeApplication(): Promise<any> {\n    this.socketModule && (await this.socketModule.close());\n    this.microservicesModule && (await this.microservicesModule.close());\n\n    await super.close();\n    this.setIsTerminated(true);\n  }\n\n  protected async dispose(): Promise<void> {\n    if (this.isTerminated) {\n      return;\n    }\n    await this.serverInstance.close();\n    this.socketModule && (await this.socketModule.close());\n    this.microservicesModule && (await this.microservicesModule.close());\n  }","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/nestjs/nest/blob/6ec0e2783d15290732447f304d8549b591b9749e/packages/microservices/nest-microservice.ts#L327-L363","documentation":"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.","triggerScenarios":"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().","commonSituations":"Hybrid apps with a gRPC server where bootstrap code calls unwrap() to grab the raw driver. Custom Server subclass authored without unwrap().","solutions":["Use a transport whose Server implements unwrap() (TCP/Redis/RMQ/MQTT/NATS) if you need the raw driver.","Add an unwrap() method to your custom Server subclass returning the underlying handle.","For gRPC, do not call unwrap() — access the gRPC client/services via the service client instead."],"exampleFix":"// before\nconst app = await NestFactory.createMicroservice(AppModule, { transport: Transport.GRPC, options: {...} });\nconst raw = app.unwrap(); // throws\n\n// after\n// gRPC does not expose unwrap(); obtain the typed service client instead\nconst svc = app.get('UserService');","handlingStrategy":"type-guard","validationCode":"function supportsUnwrap(server: any): boolean {\n  return server && 'unwrap' in server && typeof server.unwrap === 'function'\n    && !/GRPC/.test(server.constructor?.name);\n}\nif (supportsUnwrap(server)) server.unwrap();\nelse { /* obtain service client instead */ }","typeGuard":"import { ServerGrpc } from '@nestjs/microservices';\nconst supportsServerUnwrap = (s: any): boolean => !(s instanceof ServerGrpc) && 'unwrap' in s;","tryCatchPattern":"try {\n  return app.unwrap();\n} catch (e) {\n  if (/\"unwrap\" method not supported/.test(e?.message)) { /* use service client instead */ }\n  else throw e;\n}","preventionTips":["Do not call unwrap() on a gRPC server.","Add unwrap() to custom Server subclasses if you need the raw handle.","Branch generic introspection code by transport."],"tags":["microservice","server","grpc","typescript"],"analyzedSha":"6ec0e2783d15290732447f304d8549b591b9749e","analyzedAt":"2026-08-03T17:42:23.673Z","schemaVersion":2}