{"id":"62051f66ac0921cb","repo":"mongodb/node-mongodb-native","slug":"option-explain-is-not-supported-on-this-command","errorCode":null,"errorMessage":"Option \"explain\" is not supported on this command","messagePattern":"Option \"explain\" is not supported on this command","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/operations/command.ts","lineNumber":104,"sourceCode":"    //       something we'd want to reconsider. Perhaps those commands can use `Admin`\n    //       as a parent?\n    const dbNameOverride = options?.dbName || options?.authdb;\n    if (dbNameOverride) {\n      this.ns = new MongoDBNamespace(dbNameOverride, '$cmd');\n    } else {\n      this.ns = parent\n        ? parent.s.namespace.withCollection('$cmd')\n        : new MongoDBNamespace('admin', '$cmd');\n    }\n\n    this.readConcern = ReadConcern.fromOptions(options);\n    this.writeConcern = WriteConcern.fromOptions(options);\n\n    if (this.hasAspect(Aspect.EXPLAINABLE)) {\n      this.explain = Explain.fromOptions(options);\n      if (this.explain) validateExplainTimeoutOptions(this.options, this.explain);\n    } else if (options?.explain != null) {\n      throw new MongoInvalidArgumentError(`Option \"explain\" is not supported on this command`);\n    }\n  }\n\n  override get canRetryWrite(): boolean {\n    if (this.hasAspect(Aspect.EXPLAINABLE)) {\n      return this.explain == null;\n    }\n    return super.canRetryWrite;\n  }\n\n  abstract buildCommandDocument(connection: Connection, session?: ClientSession): Document;\n\n  override buildOptions(timeoutContext: TimeoutContext): ServerCommandOptions {\n    return {\n      ...this.options,\n      ...this.bsonOptions,\n      timeoutContext,\n      readPreference: this.readPreference,","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/operations/command.ts#L86-L122","documentation":"Thrown by the CommandOperation base constructor when an `explain` option is supplied for an operation that does not declare the EXPLAINABLE aspect. Only certain operations (find, aggregate, count, etc.) can be explained; passing explain to others is meaningless and rejected as MongoInvalidArgumentError before execution.","triggerScenarios":"Passing { explain: true } (or a verbosity value) to collection.insertOne, updateMany, createIndex, command runners, or any non-explainable operation. Spreading a shared options object that includes explain across all calls.","commonSituations":"Generic option-merging helpers that attach explain everywhere; debugging code that wraps every operation with explain; copy-paste from an aggregate call.","solutions":["Remove the explain option from non-explainable operations.","Only use explain with supported operations: find, aggregate, countDocuments (via aggregate), and distinct.","If using a shared options builder, branch on operation type before adding explain."],"exampleFix":"// before\nawait collection.insertOne(doc, { explain: true }); // throws\n\n// after\nawait collection.insertOne(doc);\n// explain only where supported:\nawait collection.find({}).explain();","handlingStrategy":"validation","validationCode":"const EXPLAINABLE = new Set(['find','aggregate','count','distinct']);\nif (!EXPLAINABLE.has(opName)) delete options.explain;","typeGuard":"function isExplainable(opName): boolean {\n  return ['find','aggregate','count','distinct'].includes(opName);\n}","tryCatchPattern":null,"preventionTips":["Only pass explain to find/aggregate/count/distinct","Don't merge explain into a shared options object blindly","Use collection.find().explain() for the typed path"],"tags":["explain","options","unsupported-operation"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}