nestjs/nest · error · InvalidGrpcPackageDefinitionMissingPackageDefinitionException

Invalid gRPC configuration. protoPath or packageDefinition m

Error message

Invalid gRPC configuration. protoPath or packageDefinition must be defined.

What it means

Thrown as InvalidGrpcPackageDefinitionMissingPackageDefinitionException from getGrpcPackageDefinition() when the gRPC options object defines NEITHER options.protoPath NOR options.packageDefinition. The helper needs one of these to build the package definition consumed by @grpc/grpc-js; with neither, there is no schema to load, so the call is rejected at startup before bindEvents() proceeds.

Source

Thrown at packages/microservices/helpers/grpc-helpers.ts:16

import { InvalidGrpcPackageDefinitionMissingPackageDefinitionException } from '../errors/invalid-grpc-package-definition-missing-package-definition.exception';
import { InvalidGrpcPackageDefinitionMutexException } from '../errors/invalid-grpc-package-definition-mutex.exception';
import { GrpcOptions } from '../interfaces';

export function getGrpcPackageDefinition(
  options: GrpcOptions['options'],
  grpcProtoLoaderPackage: any,
) {
  const file = options['protoPath'];
  const packageDefinition = options['packageDefinition'];

  if (file && packageDefinition) {
    throw new InvalidGrpcPackageDefinitionMutexException();
  }
  if (!file && !packageDefinition) {
    throw new InvalidGrpcPackageDefinitionMissingPackageDefinitionException();
  }

  return (
    packageDefinition ||
    grpcProtoLoaderPackage.loadSync(file, options['loader'])
  );
}

View on GitHub (pinned to 6ec0e2783d)

Solutions

1. Add options.protoPath pointing to a .proto file (string or array) plus a working loader, or add options.packageDefinition with a proto-loader PackageDefinition.
2. Double-check the exact key name (protoPath, camelCase) and that the value is defined at the time the client/server is constructed.
3. If options are built dynamically, log them before registration to confirm protoPath or packageDefinition is present.

Example fix

// before
ClientProxyFactory.create({
  transport: Transport.GRPC,
  options: { url: 'localhost:5000', package: 'user' }, // no protoPath/packageDefinition
});

// after
ClientProxyFactory.create({
  transport: Transport.GRPC,
  options: {
    url: 'localhost:5000',
    package: 'user',
    protoPath: join(__dirname, 'user.proto'),
  },
});

function validateGrpcOptions(opts: any) {
  if (!opts.protoPath && !opts.packageDefinition) {
    throw new Error('protoPath or packageDefinition is required for gRPC.');
  }
  return opts;
}
validateGrpcOptions(grpcOptions);

const hasNoProtoSource = (o: any): boolean => !o?.protoPath && !o?.packageDefinition;

// Validate at startup; this error is thrown during listen()/client creation.

When it happens

Trigger: Registering a gRPC client/server with options that omit both protoPath and packageDefinition (e.g. only supplying url/package). Typo in the option key (protoPath vs protoPath misspelled) so the real key is undefined.

Common situations: Incomplete gRPC options object copied from a partial example. Renamed/misspelled option key (proto_path, proto, protoFilePath). Options assembled via spread where protoPath was undefined at build time. Migration that removed protoPath intending to add packageDefinition but never did.

Related errors

• Invalid gRPC configuration. Both protoPath and packageDefini
• 3
• The "connect()" method is not supported in gRPC mode.
• Method is not supported in gRPC mode. Use ClientGrpc instead
• Method is not supported in gRPC mode.

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