{"id":"d1f16cea680db609","repo":"nestjs/nest","slug":"invalid-grpc-configuration-both-protopath-and-pac","errorCode":null,"errorMessage":"Invalid gRPC configuration. Both protoPath and packageDefinition cannot be defined at the same time.","messagePattern":"Invalid gRPC configuration\\. Both protoPath and packageDefinition cannot be defined at the same time\\.","errorType":"exception","errorClass":"InvalidGrpcPackageDefinitionMutexException","httpStatus":null,"severity":"error","filePath":"packages/microservices/helpers/grpc-helpers.ts","lineNumber":13,"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 InvalidGrpcPackageDefinitionMutexException from getGrpcPackageDefinition() when the gRPC options object defines BOTH options.protoPath AND options.packageDefinition. These are mutually exclusive ways to produce the package definition: protoPath tells @grpc/proto-loader to load+compile a .proto file at runtime, while packageDefinition is an already-built @grpc/proto-loader PackageDefinition. Specifying both is ambiguous, so the helper rejects it rather than silently picking one.","triggerScenarios":"Calling ClientsModule.registerAsync or ClientProxyFactory.create for Transport.GRPC with options containing both { protoPath: './x.proto', packageDefinition: fromLoader }. Mixing a static packageDefinition import with a protoPath string in the same options object.","commonSituations":"Migrating from protoPath to a precompiled packageDefinition (e.g. grpc-tools output) and forgetting to remove protoPath. Copy-pasting options from an example that used protoPath and adding packageDefinition on top. Bundler config that injects protoPath defaults while the app also supplies packageDefinition.","solutions":["Provide exactly one source: either options.protoPath (plus optional loader/package), or options.packageDefinition (a proto-loader PackageDefinition object).","If you precompiled the proto, delete protoPath from the gRPC options and pass only packageDefinition.","Keep package and (when using packageDefinition) the loader options consistent so service lookup still works."],"exampleFix":"// before\nClientProxyFactory.create({\n  transport: Transport.GRPC,\n  options: {\n    protoPath: join(__dirname, 'user.proto'),\n    packageDefinition: packageDef, // both set -> throws\n    package: 'user',\n  },\n});\n\n// after\nClientProxyFactory.create({\n  transport: Transport.GRPC,\n  options: {\n    packageDefinition: packageDef,\n    package: 'user',\n  },\n});","handlingStrategy":"validation","validationCode":"function validateGrpcOptions(opts: any) {\n  if (opts.protoPath && opts.packageDefinition) {\n    throw new Error('Provide protoPath OR packageDefinition, not both.');\n  }\n  return opts;\n}\nvalidateGrpcOptions(grpcOptions);","typeGuard":"const hasBothProtoSources = (o: any): boolean => !!(o?.protoPath && o?.packageDefinition);","tryCatchPattern":"// Startup-time validation is the right pattern; remove one of the two options before construction.","preventionTips":["Choose one schema source (protoPath or packageDefinition) and document it.","When migrating from protoPath to packageDefinition, delete protoPath.","Add a unit test asserting the options object has exactly one of the two keys."],"tags":["grpc","configuration","proto-loader","nestjs","typescript"],"analyzedSha":"6ec0e2783d15290732447f304d8549b591b9749e","analyzedAt":"2026-08-03T17:42:23.673Z","schemaVersion":2}