nestjs/nest · error · Error

Method is not supported for gRPC transport

Error message

Method is not supported for gRPC transport

What it means

Thrown by ServerGrpc.unwrap(). Unlike the TCP/Redis/RMQ/MQTT/NATS servers which hold a single raw broker handle, the gRPC server is built from many dynamically created service definitions and does not expose one underlying object to hand back; unwrap() is therefore permanently unsupported and always throws. This mirrors ClientKafka.on() and the ServerGrpc.on()/status guards — the API is intentionally absent for gRPC.

Source

Thrown at packages/microservices/server/server-grpc.ts:333

  public createStreamServiceMethod(methodHandler: Function): Function {
    return async (call: GrpcCall, callback: Function) => {
      return this.onProcessingStartHook(
        this.transportId,
        { ...call, operationId: methodHandler.name } as any,
        async () => {
          const handler = methodHandler(call.request, call.metadata, call);
          const result$ = this.transformToObservable(await handler);
          await this.writeObservableToGrpc(result$, call);

          this.onProcessingEndHook?.(this.transportId, call.request);
        },
      );
    };
  }

  public unwrap<T>(): T {
    throw new Error('Method is not supported for gRPC transport');
  }

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

  /**
   * Writes an observable to a GRPC call.
   *
   * This function will ensure that backpressure is managed while writing values
   * that come from an observable to a GRPC call.
   *
   * @param source The observable we want to write out to the GRPC call.
   * @param call The GRPC call we want to write to.
   * @returns A promise that resolves when we're done writing to the call.

View on GitHub (pinned to 6ec0e2783d)

Solutions

1. Do not call unwrap() on a ServerGrpc; there is no single underlying handle to return.
2. For low-level gRPC access, register a custom service or use the gRPC client created via createClient() / ClientsModule instead.
3. In generic code, skip unwrap() when the transport is Transport.GRPC.

Example fix

// before
const server = new ServerGrpc(options);
const grpcServer = server.unwrap(); // throws

// after
const server = new ServerGrpc(options);
// there is no raw handle; interact through the proto service clients instead

function unwrapSafe(server: any) {
  if (server instanceof ServerGrpc) return undefined; // unsupported
  return server.unwrap();
}
const raw = unwrapSafe(server);

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

try {
  return server.unwrap();
} catch (e) {
  if (/not supported for gRPC transport/.test(e?.message)) { /* use gRPC service client */ }
  else throw e;
}

When it happens

Trigger: Calling server.unwrap() (or microservice.unwrap() delegating to a gRPC server) to reach the raw @grpc/grpc-js Server. Generic introspection/tooling that calls unwrap() on every server type.

Common situations: Bootstrap code that grabs the raw driver via unwrap() across all transports, run against a gRPC server. Migrating from TCP/Redis to gRPC and keeping the unwrap() call. Custom instrumentation that expects a raw handle.

Related errors

• The "status" attribute is not supported by the gRPC transpor
• "on" method not supported by the underlying server
• "unwrap" method not supported by the underlying server
• The "connect()" method is not supported in gRPC mode.
• Method is not supported in gRPC mode. Use ClientGrpc instead

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