{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/operations/command.ts#L86-L122","documentation":"Thrown by CommandOperation's constructor when the caller passes an explain option to a command operation that does not declare the EXPLAINABLE aspect. Only certain commands (find, aggregate, etc.) can be explained; arbitrary runCommand-style operations reject explain because the server would reject it anyway.","triggerScenarios":"Calling an internal command operation with { explain: true } in its options when the operation class has not declared Aspect.EXPLAINABLE. Public API misuse via Db.command(..., { explain }) or custom Operation subclasses.","commonSituations":"Subclassing CommandOperation for a custom command and forgetting to add Aspect.EXPLAINABLE to the aspects array; passing through generic option maps that include explain by accident.","solutions":["If you need explain output, use a supported public API like collection.find().explain() or collection.aggregate(pipeline, { explain: true }).","For custom CommandOperation subclasses, declare EXPLAINABLE in the constructor: super(options); and add Aspect.EXPLAINABLE via getAspectName / aspects.","Drop the explain option if you do not actually need it for this command."],"exampleFix":"// before (custom op)\nclass MyOp extends CommandOperation {\n  constructor(parent, options) { super(parent, { ...options, explain: true }); }\n}\n\n// after\nclass MyOp extends CommandOperation {\n  constructor(parent, options) {\n    super(parent, options);\n    this.explain = Explain.fromOptions(options);\n  }\n  override get commandName() { return 'myCmd' as const; }\n  // declare EXPLAINABLE aspect where the operation is registered\n  buildCommandDocument() { /* ... */ }\n}","handlingStrategy":"validation","validationCode":"if (options?.explain != null && !operation.hasAspect?.(EXPLAINABLE)) {\n  delete options.explain;\n  // or throw: 'explain not supported here'\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer the public .explain() method on cursors instead of passing explain through options.","When subclassing CommandOperation, declare Aspect.EXPLAINABLE explicitly."],"tags":["explain","operations","api-misuse"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}