mongodb/node-mongodb-native · error · MongoServerError

<dynamic: server write error propagated via MongoServerError

Error message

<dynamic: server write error propagated via MongoServerError(res.writeErrors[0])>

What it means

In DeleteOneOperation.handleOk (src/operations/delete.ts:117), after a successful round-trip, the driver checks for per-document write errors in the response. If `writeErrors` is present, the first entry is wrapped in a MongoServerError and thrown. This is how the driver surfaces individual document-level write failures such as duplicate-key or schema-validation errors.

Source

Thrown at src/operations/delete.ts:117

    return command;
  }
}

export class DeleteOneOperation extends DeleteOperation {
  constructor(ns: MongoDBCollectionNamespace, filter: Document, options: DeleteOptions) {
    super(ns, [makeDeleteStatement(filter, { ...options, limit: 1 })], options);
  }

  override handleOk(
    response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>
  ): DeleteResult {
    const res = super.handleOk(response);

    // @ts-expect-error Explain commands have broken TS
    if (this.explain) return res;

    if (res.code) throw new MongoServerError(res);
    if (res.writeErrors) throw new MongoServerError(res.writeErrors[0]);

    return {
      acknowledged: this.writeConcern?.w !== 0,
      deletedCount: res.n
    };
  }
}
export class DeleteManyOperation extends DeleteOperation {
  constructor(ns: MongoDBCollectionNamespace, filter: Document, options: DeleteOptions) {
    super(ns, [makeDeleteStatement(filter, options)], options);
  }

  override handleOk(
    response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>
  ): DeleteResult {
    const res = super.handleOk(response);

    // @ts-expect-error Explain commands have broken TS

View on GitHub (pinned to 3366c21a63)

Solutions

1. Read err.writeErrors (or err.errmsg) to see the per-document failure detail; the message and code come from the server.
2. If err.code is 121 (DocumentValidationFailure), review the collection's $jsonSchema validator and the document being deleted.
3. For transient failures, check for the RetryableError label before retrying.
4. If the error is not actionable, surface it to the user with the original server message.

Example fix

// before
await collection.deleteOne({ sku: 'X-1' });

// after
try {
  await collection.deleteOne({ sku: 'X-1' });
} catch (err) {
  if (err instanceof MongoServerError && err.writeErrors) {
    const [first] = err.writeErrors;
    console.error(`delete write error ${first.code}: ${first.errmsg}`);
  }
  throw err;
}

try {
  await collection.deleteOne(filter);
} catch (err) {
  if (err instanceof MongoServerError && err.writeErrors) {
    const first = err.writeErrors[0];
    // handle first.code (e.g. 121 = validation)
  } else throw err;
}

When it happens

Trigger: collection.deleteOne(filter) where the server applies the delete but reports a write error — most commonly a document-validation failure or a write concern error tied to the single document.

Common situations: Collection has a JSON schema validator that rejects the operation context, or a write concern error is reported per-document. Because deleteOne affects a single document, the writeErrors array typically contains exactly one entry.

Related errors

• <dynamic: server error response propagated via MongoServerEr
• Update document requires atomic operators
• Replacement document must not use atomic operators
• Bulk find operation must specify a selector
• Operation must be an object with an operation key

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/ccb699ac76c460a1.json. Report an issue: GitHub.