{"id":"dbeb4297268dfcca","repo":"nestjs/nest","slug":"invalid-grpc-configuration-protopath-or-packagede","errorCode":null,"errorMessage":"Invalid gRPC configuration. protoPath or packageDefinition must be defined.","messagePattern":"Invalid gRPC configuration\\. protoPath or packageDefinition must be defined\\.","errorType":"exception","errorClass":"InvalidGrpcPackageDefinitionMissingPackageDefinitionException","httpStatus":null,"severity":"error","filePath":"packages/microservices/helpers/grpc-helpers.ts","lineNumber":16,"sourceCode":"import { InvalidGrpcPackageDefinitionMissingPackageDefinitionException } from '../errors/invalid-grpc-package-definition-missing-package-definition.exception';\nimport { InvalidGrpcPackageDefinitionMutexException } from '../errors/invalid-grpc-package-definition-mutex.exception';\nimport { GrpcOptions } from '../interfaces';\n\nexport function getGrpcPackageDefinition(\n  options: GrpcOptions['options'],\n  grpcProtoLoaderPackage: any,\n) {\n  const file = options['protoPath'];\n  const packageDefinition = options['packageDefinition'];\n\n  if (file && packageDefinition) {\n    throw new InvalidGrpcPackageDefinitionMutexException();\n  }\n  if (!file && !packageDefinition) {\n    throw new InvalidGrpcPackageDefinitionMissingPackageDefinitionException();\n  }\n\n  return (\n    packageDefinition ||\n    grpcProtoLoaderPackage.loadSync(file, options['loader'])\n  );\n}\n","sourceCodeStart":1,"sourceCodeEnd":24,"githubUrl":"https://github.com/nestjs/nest/blob/6ec0e2783d15290732447f304d8549b591b9749e/packages/microservices/helpers/grpc-helpers.ts#L1-L24","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add options.protoPath pointing to a .proto file (string or array) plus a working loader, or add options.packageDefinition with a proto-loader PackageDefinition.","Double-check the exact key name (protoPath, camelCase) and that the value is defined at the time the client/server is constructed.","If options are built dynamically, log them before registration to confirm protoPath or packageDefinition is present."],"exampleFix":"// before\nClientProxyFactory.create({\n  transport: Transport.GRPC,\n  options: { url: 'localhost:5000', package: 'user' }, // no protoPath/packageDefinition\n});\n\n// after\nClientProxyFactory.create({\n  transport: Transport.GRPC,\n  options: {\n    url: 'localhost:5000',\n    package: 'user',\n    protoPath: join(__dirname, 'user.proto'),\n  },\n});","handlingStrategy":"validation","validationCode":"function validateGrpcOptions(opts: any) {\n  if (!opts.protoPath && !opts.packageDefinition) {\n    throw new Error('protoPath or packageDefinition is required for gRPC.');\n  }\n  return opts;\n}\nvalidateGrpcOptions(grpcOptions);","typeGuard":"const hasNoProtoSource = (o: any): boolean => !o?.protoPath && !o?.packageDefinition;","tryCatchPattern":"// Validate at startup; this error is thrown during listen()/client creation.","preventionTips":["Always set protoPath (or packageDefinition) in gRPC options.","Double-check the camelCase key name protoPath.","Log the resolved options object before registration to catch undefined values."],"tags":["grpc","configuration","proto-loader","nestjs","typescript"],"analyzedSha":"6ec0e2783d15290732447f304d8549b591b9749e","analyzedAt":"2026-08-03T17:42:23.673Z","schemaVersion":2}