From f289c539a4d58b536d06d8fa7322b77b3c8c67fb Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 10:54:03 -0400 Subject: [PATCH 01/26] DOCSP-30350 Java Write Error Page (cherry picked from commit 7de199dd9c0aaf5360328952a9c839752494cada) --- source/operation-error-handling.txt | 105 ++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 source/operation-error-handling.txt diff --git a/source/operation-error-handling.txt b/source/operation-error-handling.txt new file mode 100644 index 000000000..c0841fd83 --- /dev/null +++ b/source/operation-error-handling.txt @@ -0,0 +1,105 @@ +.. _java-operation-errors: + +============================== +Write Operation Error Handling +============================== + +.. meta:: + :description: Understand how to handle operation errors in the MongoDB Java Sync Driver, including error types like WriteErrror and ConnectionPoolCleared. + +.. contents:: + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +This page describes write errors you might encounter when +using the {+driver-long+} to perform MongoDB write operations. Once you +understand the types of write operation errors that the driver raises, you can take +appropriate actions to either handle them or correct the error-causing code. + +.. note:: + + This page addresses only write operation error handling. If you encounter + any other issues with MongoDB or the driver, visit the following + resources: + + - :ref:`java-connection-troubleshooting` for potential solutions to + issues you might encounter when connecting to a MongoDB deployment + - :ref:`java-issues-and-help` page for information about reporting bugs, + contributing to the driver, and finding more resources + - :community-forum:`MongoDB Community Forums ` for questions, + discussions, or general technical support + +Write Error Types +----------------- + +If the driver encounters an error while performing an write operation, it +returns an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. + +The ``WriteError`` type contains the following methods: + + - ``getCode``: returns the code associated with this error. + - ``getMessage``: returns the message associated with this error. + - ``getDetails``: returns a BSON Document with details associated with this + error, which may be empty. + - ``getCategory``: returns the category of the write error as an + `ErrorCategory<{+core-api+}/ErrorCategory.html>`__ object. The + enum ``ErrorCategory`` can be one of the following options: + + - ``DUPLICATE_KEY``: you provided duplicate key to a method + - ``EXECUTION_TIMEOUT``: the driver timed out + - ``UNCATEGORIZED``: the error has no category + +The `BulkWriteError<{+core-api+}/bulk/BulkWriteError.html>`__ type extends +``WriteError`` and inherits the above methods. The `WriteConcernError +<{+core-api+}/bulk/WriteConcernError.html>`__ is not related to the ``WriteError`` type. + +Write Error +~~~~~~~~~~~ + +The driver raises a ``WriteError`` error for any errors that it +encounters when performing a write operation that are not related to +satisfying the write concern. Because there are many causes for this +error, the ``WriteError`` type contains fields that describe the type of +write error and reason for the error. + +For example, the driver raises a ``WriteError`` error if you attempt to +insert a document into a collection that violates the collection's +schema validation rules. Suppose the collection has a rule where the +value of the ``quantity`` field must be an ``int`` type. If you +attempt to insert a document where the value of ``quantity`` is +``"three"``, the driver prints the following error message: + +.. code-block:: none + :copyable: false + :emphasize-lines: 2-3 + + Error: Error { kind: Write(WriteError(WriteError { code: 121, code_name: + None, message: "Document failed validation", details: + Some(Document({"failingDocumentId": Int32(1), "details": + Document({"operatorName": String("$jsonSchema"), "title": + String("Numerical Validation"), "schemaRulesNotSatisfied": + Array(...)})})) })), labels: {}, + wire_version: None, source: None } + +In the preceding error message, the ``message`` field describes the +reason for the error, and the ``details`` field provides specific +details about the failing operation. To address this error, you must +either revise the document to adhere to the schema validation rules or +bypass validation. + +Write Concern Error +~~~~~~~~~~~~~~~~~~~ + +The driver raises a ``WriteConcernError`` error when you perform a write +operation and the driver cannot satisfy the specified write concern. For +example, if you specify a write concern of ``majority`` for +operations on a replica set with three nodes, the driver returns +this error if the write operation propagates only to one node. + +To learn more about write concerns, see :manual:`Write Concern +` in the Server manual. \ No newline at end of file From 6bd5d2b15d35dc92081bfb13635a2a5100658a26 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 11:04:45 -0400 Subject: [PATCH 02/26] DOCSP-30350 add to toc tree and fix links (cherry picked from commit 51772d1b5808d8b0f487642fadd53633ace24597) --- source/crud.txt | 1 + source/operation-error-handling.txt | 24 ++++++++++-------------- 2 files changed, 11 insertions(+), 14 deletions(-) diff --git a/source/crud.txt b/source/crud.txt index 9f20f84af..024f612d6 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -32,3 +32,4 @@ CRUD Operations - :ref:`Collations ` - :ref:`Large File Storage with GridFS ` - :ref:`Configure Custom CRUD Settings ` +- :ref:`Write Operation Error Handling ` diff --git a/source/operation-error-handling.txt b/source/operation-error-handling.txt index c0841fd83..abb7a1884 100644 --- a/source/operation-error-handling.txt +++ b/source/operation-error-handling.txt @@ -27,8 +27,8 @@ appropriate actions to either handle them or correct the error-causing code. any other issues with MongoDB or the driver, visit the following resources: - - :ref:`java-connection-troubleshooting` for potential solutions to - issues you might encounter when connecting to a MongoDB deployment + - :ref:`java-connection-troubleshooting` for potential solutions to issues + you might encounter when connecting to a MongoDB deployment - :ref:`java-issues-and-help` page for information about reporting bugs, contributing to the driver, and finding more resources - :community-forum:`MongoDB Community Forums ` for questions, @@ -42,21 +42,17 @@ returns an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. The ``WriteError`` type contains the following methods: - - ``getCode``: returns the code associated with this error. - - ``getMessage``: returns the message associated with this error. - - ``getDetails``: returns a BSON Document with details associated with this + - `getCode <{+core-api+}/WriteError.html#getCode()>`__: returns the code associated with this error. + - `getMessage <{+core-api+}/WriteError.html#getMessage()>`__: returns the message associated with this error. + - `getDetails <{+core-api+}/WriteError.html#getDetails()>`__: returns a BSON Document with details associated with this error, which may be empty. - - ``getCategory``: returns the category of the write error as an - `ErrorCategory<{+core-api+}/ErrorCategory.html>`__ object. The - enum ``ErrorCategory`` can be one of the following options: + - `getCategory <{+core-api+}/WriteError.html#getCategory()>`__: returns the category of the write error as an + `ErrorCategory <{+core-api+}/ErrorCategory.html>`__ object. - - ``DUPLICATE_KEY``: you provided duplicate key to a method - - ``EXECUTION_TIMEOUT``: the driver timed out - - ``UNCATEGORIZED``: the error has no category - -The `BulkWriteError<{+core-api+}/bulk/BulkWriteError.html>`__ type extends +The `BulkWriteError <{+core-api+}/bulk/BulkWriteError.html>`__ type extends ``WriteError`` and inherits the above methods. The `WriteConcernError -<{+core-api+}/bulk/WriteConcernError.html>`__ is not related to the ``WriteError`` type. +<{+core-api+}/bulk/WriteConcernError.html>`__ is not related to the +``WriteError`` type and details errors relating to the write concern. Write Error ~~~~~~~~~~~ From 4fef535546002d9c132fde612d434e1aa63af3ee Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 11:23:19 -0400 Subject: [PATCH 03/26] DOCSP-30350 toc tree update and editing (cherry picked from commit ede2dcdd6ccb7c162444fd648808bb6cc6383a79) --- source/crud.txt | 1 + .../{ => crud}/operation-error-handling.txt | 25 ++++++++++++------- 2 files changed, 17 insertions(+), 9 deletions(-) rename source/{ => crud}/operation-error-handling.txt (80%) diff --git a/source/crud.txt b/source/crud.txt index 024f612d6..f8cf5517e 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -19,6 +19,7 @@ CRUD Operations Collations Large File Storage with GridFS Configure Custom CRUD Settings + Write Operation Error Handling - :ref:`Insert Documents ` - :ref:`Query Documents ` diff --git a/source/operation-error-handling.txt b/source/crud/operation-error-handling.txt similarity index 80% rename from source/operation-error-handling.txt rename to source/crud/operation-error-handling.txt index abb7a1884..1f40fccfb 100644 --- a/source/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -42,17 +42,24 @@ returns an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. The ``WriteError`` type contains the following methods: - - `getCode <{+core-api+}/WriteError.html#getCode()>`__: returns the code associated with this error. - - `getMessage <{+core-api+}/WriteError.html#getMessage()>`__: returns the message associated with this error. - - `getDetails <{+core-api+}/WriteError.html#getDetails()>`__: returns a BSON Document with details associated with this - error, which may be empty. - - `getCategory <{+core-api+}/WriteError.html#getCategory()>`__: returns the category of the write error as an - `ErrorCategory <{+core-api+}/ErrorCategory.html>`__ object. + - ``getCode``: returns the code associated with this error + - ``getMessage``: returns the message associated with this error + - ``getDetails``: returns a BSON Document with details associated with this + error, which may be empty + - ``getCategory``: returns the category of the write error as an + `ErrorCategory <{+core-api+}/ErrorCategory.html>`__ object The `BulkWriteError <{+core-api+}/bulk/BulkWriteError.html>`__ type extends -``WriteError`` and inherits the above methods. The `WriteConcernError -<{+core-api+}/bulk/WriteConcernError.html>`__ is not related to the -``WriteError`` type and details errors relating to the write concern. +``WriteError`` and inherits the above methods. This type is used for bulk +operations and includes an ``index`` field that identifies the item in the bulk +operation that led to the error. + +The `WriteConcernError <{+core-api+}/bulk/WriteConcernError.html>`__ is not +related to the ``WriteError`` type and details errors relating to the write +concern. In addition to the ``getCode``, ``getMessage``, and ``getDetails`` +methods, ``WriteConcernError`` has the ``getCodeName`` method, which returns the +name associated with the error code. This type does not have the ``getCategory`` +method. Write Error ~~~~~~~~~~~ From ed39387339160e4b9921e08a53d64000dfffd34e Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 12:06:44 -0400 Subject: [PATCH 04/26] DOCSP-30350 code blocks and update write/bulkwrite sections (cherry picked from commit e657ce8f70f59ec9d9595b249c0dc2ae0b650455) --- source/crud/operation-error-handling.txt | 63 +++++++++++++----------- 1 file changed, 34 insertions(+), 29 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 1f40fccfb..5d4fcf7c4 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -52,11 +52,11 @@ The ``WriteError`` type contains the following methods: The `BulkWriteError <{+core-api+}/bulk/BulkWriteError.html>`__ type extends ``WriteError`` and inherits the above methods. This type is used for bulk operations and includes an ``index`` field that identifies the item in the bulk -operation that led to the error. +operation that caused the error. The `WriteConcernError <{+core-api+}/bulk/WriteConcernError.html>`__ is not -related to the ``WriteError`` type and details errors relating to the write -concern. In addition to the ``getCode``, ``getMessage``, and ``getDetails`` +related to the ``WriteError`` type and details errors relating to the :ref:`write +concern `. In addition to the ``getCode``, ``getMessage``, and ``getDetails`` methods, ``WriteConcernError`` has the ``getCodeName`` method, which returns the name associated with the error code. This type does not have the ``getCategory`` method. @@ -65,35 +65,40 @@ Write Error ~~~~~~~~~~~ The driver raises a ``WriteError`` error for any errors that it -encounters when performing a write operation that are not related to -satisfying the write concern. Because there are many causes for this -error, the ``WriteError`` type contains fields that describe the type of -write error and reason for the error. - -For example, the driver raises a ``WriteError`` error if you attempt to -insert a document into a collection that violates the collection's -schema validation rules. Suppose the collection has a rule where the -value of the ``quantity`` field must be an ``int`` type. If you -attempt to insert a document where the value of ``quantity`` is -``"three"``, the driver prints the following error message: +encounters when performing single write operations that are not related to +satisfying the write concern. + +For example, the driver raises a ``WriteError`` error if you attempt to insert a +document into a collection with an ObjectId value that already exists in the +collection. Suppose the collection has an existing document with an ``ObjectId`` of `1`. If you attempt to insert a document +where the value of ``ObjectId`` is ``1``, the driver prints the following +error message: .. code-block:: none :copyable: false - :emphasize-lines: 2-3 - - Error: Error { kind: Write(WriteError(WriteError { code: 121, code_name: - None, message: "Document failed validation", details: - Some(Document({"failingDocumentId": Int32(1), "details": - Document({"operatorName": String("$jsonSchema"), "title": - String("Numerical Validation"), "schemaRulesNotSatisfied": - Array(...)})})) })), labels: {}, - wire_version: None, source: None } - -In the preceding error message, the ``message`` field describes the -reason for the error, and the ``details`` field provides specific -details about the failing operation. To address this error, you must -either revise the document to adhere to the schema validation rules or -bypass validation. + + WriteError: { code: 11000, message: "E11000 duplicate key error collection: + testDB.testCollection index: _id_ dup key: { _id: 1 }", details: {} } + +In the preceding error message, the ``message`` field describes the reason for +the error, and the ``details`` field provides specific details about the failing +operation. To address this error, you must revise the document to have a unique +``ObjectId``. + +Bulk Write Error +---------------- + +If this same example was run in during bulk write operation, an additional field +would be added to the error detailing the index of the item with the duplicate +``ObjectId`` + +.. code-block:: none + :copyable: false + :emphasize-lines: 1 + + BulkWriteError{index=2, code=11000, message='E11000 duplicate key error + collection: testDB.testCollection index: _id_ dup key: { _id: 1 }', + details=Document{{}}} Write Concern Error ~~~~~~~~~~~~~~~~~~~ From f88722bba8e0a42b30a8ba5aec954debcf0111e3 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 13:19:05 -0400 Subject: [PATCH 05/26] DOCSP-30350 Updating grammar and Write/bulk Write error messages (cherry picked from commit 8341e97c17093c1b90345691124b9b288d2b3438) --- source/crud/operation-error-handling.txt | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 5d4fcf7c4..9a8c2e756 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -37,7 +37,7 @@ appropriate actions to either handle them or correct the error-causing code. Write Error Types ----------------- -If the driver encounters an error while performing an write operation, it +If the driver encounters an error while performing a write operation, it returns an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. The ``WriteError`` type contains the following methods: @@ -61,6 +61,8 @@ methods, ``WriteConcernError`` has the ``getCodeName`` method, which returns the name associated with the error code. This type does not have the ``getCategory`` method. +.. _java_error_write_errors: + Write Error ~~~~~~~~~~~ @@ -70,7 +72,7 @@ satisfying the write concern. For example, the driver raises a ``WriteError`` error if you attempt to insert a document into a collection with an ObjectId value that already exists in the -collection. Suppose the collection has an existing document with an ``ObjectId`` of `1`. If you attempt to insert a document +collection. Suppose the collection has an existing document with an ``ObjectId`` of `1`. If you attempt to insert another document where the value of ``ObjectId`` is ``1``, the driver prints the following error message: @@ -78,7 +80,7 @@ error message: :copyable: false WriteError: { code: 11000, message: "E11000 duplicate key error collection: - testDB.testCollection index: _id_ dup key: { _id: 1 }", details: {} } + testDB.testCollection index: _id_ dup key: { _id: 1 }", details: Document{{}}} } In the preceding error message, the ``message`` field describes the reason for the error, and the ``details`` field provides specific details about the failing @@ -88,17 +90,18 @@ operation. To address this error, you must revise the document to have a unique Bulk Write Error ---------------- -If this same example was run in during bulk write operation, an additional field -would be added to the error detailing the index of the item with the duplicate -``ObjectId`` +If the same example were run as a bulk write operation, the `index` field +containing the index of the item with the duplicate ``ObjectId`` would be added +to the message. For example, if the index of the item that produced the error is +`2`, the driver would print the following error message: .. code-block:: none :copyable: false :emphasize-lines: 1 - BulkWriteError{index=2, code=11000, message='E11000 duplicate key error + BulkWriteError{ index: 2, code: 11000, message: 'E11000 duplicate key error collection: testDB.testCollection index: _id_ dup key: { _id: 1 }', - details=Document{{}}} + details: Document{{}} } Write Concern Error ~~~~~~~~~~~~~~~~~~~ From e506c1b637adfc7feebf14fbc46a282e5104e10e Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 13:21:22 -0400 Subject: [PATCH 06/26] DOCSP30350 fix code example format (cherry picked from commit 1d219ee6951111c15522fbf370973159691e4b76) --- source/crud/operation-error-handling.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 9a8c2e756..a5bb3b0f9 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -79,8 +79,9 @@ error message: .. code-block:: none :copyable: false - WriteError: { code: 11000, message: "E11000 duplicate key error collection: - testDB.testCollection index: _id_ dup key: { _id: 1 }", details: Document{{}}} } +WriteError{code=11000, message='E11000 duplicate key error +collection: testDB.testCollection index: _id_ dup key: { _id: 1 }', +details=Document{{}}} In the preceding error message, the ``message`` field describes the reason for the error, and the ``details`` field provides specific details about the failing @@ -99,9 +100,9 @@ to the message. For example, if the index of the item that produced the error is :copyable: false :emphasize-lines: 1 - BulkWriteError{ index: 2, code: 11000, message: 'E11000 duplicate key error + BulkWriteError{index=2, code=11000, message='E11000 duplicate key error collection: testDB.testCollection index: _id_ dup key: { _id: 1 }', - details: Document{{}} } + details=Document{{}}} Write Concern Error ~~~~~~~~~~~~~~~~~~~ From b7a08255e4b2d6044216437758eb7ec3e7fd8d7b Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 13:28:06 -0400 Subject: [PATCH 07/26] DOCSP-30350 code examples and additional getCategory information (cherry picked from commit d60da9ec43691f0cc1207667776c8988778f7521) --- source/crud/operation-error-handling.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index a5bb3b0f9..bdfcc897b 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -79,15 +79,18 @@ error message: .. code-block:: none :copyable: false -WriteError{code=11000, message='E11000 duplicate key error -collection: testDB.testCollection index: _id_ dup key: { _id: 1 }', -details=Document{{}}} + WriteError{code=11000, message='E11000 duplicate key error + collection: testDB.testCollection index: _id_ dup key: { _id: 1 }', + details=Document{{}}} In the preceding error message, the ``message`` field describes the reason for the error, and the ``details`` field provides specific details about the failing operation. To address this error, you must revise the document to have a unique ``ObjectId``. +If you run the ``getCategory`` method on this ``WriteError`` object, it would +return an ``ErrorCategory`` of ``DUPLICATE_KEY``. + Bulk Write Error ---------------- From 7a830c3c54af1c097d08f4c395f7d1ac3457f711 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 13:44:00 -0400 Subject: [PATCH 08/26] DOCSP-30350 fixing up minor issues with page, final check (cherry picked from commit 2076d6b41d6b544cc0fed68d09d7aed001722062) --- source/crud/operation-error-handling.txt | 59 ++++++++++++------------ 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index bdfcc897b..7bc67ce9d 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -1,8 +1,8 @@ .. _java-operation-errors: -============================== -Write Operation Error Handling -============================== +============================= +Troubleshooting Write Errors +============================= .. meta:: :description: Understand how to handle operation errors in the MongoDB Java Sync Driver, including error types like WriteErrror and ConnectionPoolCleared. @@ -54,12 +54,11 @@ The `BulkWriteError <{+core-api+}/bulk/BulkWriteError.html>`__ type extends operations and includes an ``index`` field that identifies the item in the bulk operation that caused the error. -The `WriteConcernError <{+core-api+}/bulk/WriteConcernError.html>`__ is not -related to the ``WriteError`` type and details errors relating to the :ref:`write -concern `. In addition to the ``getCode``, ``getMessage``, and ``getDetails`` -methods, ``WriteConcernError`` has the ``getCodeName`` method, which returns the -name associated with the error code. This type does not have the ``getCategory`` -method. +The `WriteConcernError <{+core-api+}/bulk/WriteConcernError.html>`__ details +errors related to the :manual:`write concern `. It +does not extend the ``WriteError`` type, but has the same methods, except for +`getCategory`. In addition, ``WriteConcernError`` has the ``getCodeName`` +method, which returns the name associated with the error code. .. _java_error_write_errors: @@ -70,42 +69,44 @@ The driver raises a ``WriteError`` error for any errors that it encounters when performing single write operations that are not related to satisfying the write concern. -For example, the driver raises a ``WriteError`` error if you attempt to insert a -document into a collection with an ObjectId value that already exists in the -collection. Suppose the collection has an existing document with an ``ObjectId`` of `1`. If you attempt to insert another document -where the value of ``ObjectId`` is ``1``, the driver prints the following -error message: +For example, the driver raises a ``WriteError`` error if you attempt to +insert a document into a collection that violates the collection's +schema validation rules. Suppose the collection has a rule where the +value of the ``quantity`` field must be an ``int`` type. If you +attempt to insert a document where the value of ``quantity`` is +``"three"``, the driver prints the following error message: .. code-block:: none :copyable: false - WriteError{code=11000, message='E11000 duplicate key error - collection: testDB.testCollection index: _id_ dup key: { _id: 1 }', - details=Document{{}}} + WriteError{ code=121, message='Document failed validation', + details=Document{{operator=$jsonSchema, schema={type=object, + required=["name", "age"], properties={name={type=string}, age={type=int, + minimum=18}}}} } + } In the preceding error message, the ``message`` field describes the reason for the error, and the ``details`` field provides specific details about the failing -operation. To address this error, you must revise the document to have a unique -``ObjectId``. - -If you run the ``getCategory`` method on this ``WriteError`` object, it would -return an ``ErrorCategory`` of ``DUPLICATE_KEY``. +operation, in this case it provides the schema rules. To address this error, you +must either revise the document to adhere to the schema validation rules or +bypass validation. Bulk Write Error ---------------- -If the same example were run as a bulk write operation, the `index` field -containing the index of the item with the duplicate ``ObjectId`` would be added -to the message. For example, if the index of the item that produced the error is -`2`, the driver would print the following error message: +If the same example were run as a bulk write operation, the ``index`` field +containing the index of the erring item would be added to the message. For +example, if the ``index`` of the item that violated the schema is ``2``, the driver +would print the following error message: .. code-block:: none :copyable: false :emphasize-lines: 1 - BulkWriteError{index=2, code=11000, message='E11000 duplicate key error - collection: testDB.testCollection index: _id_ dup key: { _id: 1 }', - details=Document{{}}} + BulkWriteError{ index=2, code=121, message='Document failed validation', + details=Document{{operator=$jsonSchema, schema={type=object, + required=["name", "age"], properties={name={type=string}, age={type=int, + minimum=18}}}} } Write Concern Error ~~~~~~~~~~~~~~~~~~~ From a288c4c46459ec0b0a19fb20d4694ea08a5fe294 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 14:29:50 -0400 Subject: [PATCH 09/26] DOCSP30350 add exceptions not just errors to doc (cherry picked from commit 402ce2e6f7ed64636776c9ab6c336607c4f72f64) --- source/crud/operation-error-handling.txt | 133 +++++++++++------------ 1 file changed, 61 insertions(+), 72 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 7bc67ce9d..7078e76de 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -1,11 +1,11 @@ .. _java-operation-errors: -============================= +============================ Troubleshooting Write Errors -============================= +============================ .. meta:: - :description: Understand how to handle operation errors in the MongoDB Java Sync Driver, including error types like WriteErrror and ConnectionPoolCleared. + :description: Understand how to handle write exceptions in the MongoDB Java Sync Driver, including error types like WriteError and BulkWriteError. .. contents:: :local: @@ -16,14 +16,14 @@ Troubleshooting Write Errors Overview -------- -This page describes write errors you might encounter when +This page describes write exceptions you might encounter when using the {+driver-long+} to perform MongoDB write operations. Once you -understand the types of write operation errors that the driver raises, you can take +understand the types of write exceptions that the driver raises, you can take appropriate actions to either handle them or correct the error-causing code. .. note:: - This page addresses only write operation error handling. If you encounter + This page addresses only write exception handling. If you encounter any other issues with MongoDB or the driver, visit the following resources: @@ -34,42 +34,29 @@ appropriate actions to either handle them or correct the error-causing code. - :community-forum:`MongoDB Community Forums ` for questions, discussions, or general technical support -Write Error Types ------------------ +Write Error +----------- If the driver encounters an error while performing a write operation, it -returns an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. - -The ``WriteError`` type contains the following methods: - - - ``getCode``: returns the code associated with this error - - ``getMessage``: returns the message associated with this error - - ``getDetails``: returns a BSON Document with details associated with this - error, which may be empty - - ``getCategory``: returns the category of the write error as an - `ErrorCategory <{+core-api+}/ErrorCategory.html>`__ object +creates an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. -The `BulkWriteError <{+core-api+}/bulk/BulkWriteError.html>`__ type extends -``WriteError`` and inherits the above methods. This type is used for bulk -operations and includes an ``index`` field that identifies the item in the bulk -operation that caused the error. +The ``WriteError`` type contains the following fields: -The `WriteConcernError <{+core-api+}/bulk/WriteConcernError.html>`__ details -errors related to the :manual:`write concern `. It -does not extend the ``WriteError`` type, but has the same methods, except for -`getCategory`. In addition, ``WriteConcernError`` has the ``getCodeName`` -method, which returns the name associated with the error code. + - ``code``: the code associated with the error + - ``message``: a message explaining the error + - ``details``: an optional field containing details associated with the error -.. _java_error_write_errors: +.. _java_error_write_exceptions: -Write Error -~~~~~~~~~~~ +Write Exception +--------------- -The driver raises a ``WriteError`` error for any errors that it -encounters when performing single write operations that are not related to -satisfying the write concern. +The driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>` for +any errors that it encounters when performing single write operations that are +not related to satisfying the write concern. The ``WriteException`` type +contains the ``WriteError`` object and a ``ServerAddress`` object. -For example, the driver raises a ``WriteError`` error if you attempt to +For example, the driver raises a ``MongoWriteException`` if you attempt to insert a document into a collection that violates the collection's schema validation rules. Suppose the collection has a rule where the value of the ``quantity`` field must be an ``int`` type. If you @@ -78,44 +65,46 @@ attempt to insert a document where the value of ``quantity`` is .. code-block:: none :copyable: false - - WriteError{ code=121, message='Document failed validation', - details=Document{{operator=$jsonSchema, schema={type=object, - required=["name", "age"], properties={name={type=string}, age={type=int, - minimum=18}}}} } - } - -In the preceding error message, the ``message`` field describes the reason for -the error, and the ``details`` field provides specific details about the failing -operation, in this case it provides the schema rules. To address this error, you -must either revise the document to adhere to the schema validation rules or -bypass validation. - -Bulk Write Error ----------------- - -If the same example were run as a bulk write operation, the ``index`` field -containing the index of the erring item would be added to the message. For -example, if the ``index`` of the item that violated the schema is ``2``, the driver -would print the following error message: + :emphasize-lines: 1, 4-6 + + Exception in thread "main" com.mongodb.MongoWriteException: Document failed validation at + com.mongodb.internal.connection.ProtocolHelper.getWriteException(ProtocolHelper.java:228) + ... + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Apple","quantity":"three"} } } at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + +In the preceding error message, the ``MongoWriteException`` object describes the +reason for the error, and the ``Caused by`` field provides details from the +``WriteError`` object about the failing operation. To address this error, you must +either revise the document to adhere to the schema validation rules or bypass +validation. + +Bulk Write Exception +-------------------- + +If the same example were run as a bulk write operation, a +`MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__ would be +thrown. A ``MongoBulkWriteException`` can contain a list of errors associated +with the same bulk write operation. For example, if you attempt to insert two +documents that violate the collection's schema, the error message would appear +as follows: .. code-block:: none :copyable: false - :emphasize-lines: 1 - - BulkWriteError{ index=2, code=121, message='Document failed validation', - details=Document{{operator=$jsonSchema, schema={type=object, - required=["name", "age"], properties={name={type=string}, age={type=int, - minimum=18}}}} } - -Write Concern Error -~~~~~~~~~~~~~~~~~~~ - -The driver raises a ``WriteConcernError`` error when you perform a write -operation and the driver cannot satisfy the specified write concern. For -example, if you specify a write concern of ``majority`` for -operations on a replica set with three nodes, the driver returns -this error if the write operation propagates only to one node. - -To learn more about write concerns, see :manual:`Write Concern -` in the Server manual. \ No newline at end of file + :emphasize-lines: 1, 5, 9 + + Exception in thread "main" com.mongodb.MongoBulkWriteException: Bulk write operation result had errors + at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:258) + ... + at BulkWriteMultipleValidationErrorsExample.main(BulkWriteMultipleValidationErrorsExample.java:30) + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, message='Document failed validation', details={ operator: "$jsonSchema", schemaRules: { bsonType: "int", description: "must be an integer" }, offendingDocument: {"name":"Apple","quantity":"three"} }} + at com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + ... 19 more + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, message='Document failed validation', details={ operator: "$jsonSchema", schemaRules: { bsonType: "int", description: "must be an integer" }, offendingDocument: {"name":"Banana","quantity":"ten"} }} + at com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + ... 19 more From 4ad76f4e242ffd8d5395eed4a01d41e2e06d4f0d Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 14:35:00 -0400 Subject: [PATCH 10/26] DOCSP-30350 fixing formatting (cherry picked from commit 11785f55381a68317aa2790e9adf07d67b689d03) --- source/crud/operation-error-handling.txt | 48 ++++++++++++++---------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 7078e76de..4577c3db1 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -1,8 +1,8 @@ .. _java-operation-errors: -============================ -Troubleshooting Write Errors -============================ +================================ +Troubleshooting Write Exceptions +================================ .. meta:: :description: Understand how to handle write exceptions in the MongoDB Java Sync Driver, including error types like WriteError and BulkWriteError. @@ -35,7 +35,7 @@ appropriate actions to either handle them or correct the error-causing code. discussions, or general technical support Write Error ------------ +~~~~~~~~~~~ If the driver encounters an error while performing a write operation, it creates an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. @@ -51,10 +51,10 @@ The ``WriteError`` type contains the following fields: Write Exception --------------- -The driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>` for +The driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ for any errors that it encounters when performing single write operations that are -not related to satisfying the write concern. The ``WriteException`` type -contains the ``WriteError`` object and a ``ServerAddress`` object. +not related to satisfying the write concern. The ``MongoWriteException`` type +contains the ``WriteError`` object. For example, the driver raises a ``MongoWriteException`` if you attempt to insert a document into a collection that violates the collection's @@ -65,7 +65,7 @@ attempt to insert a document where the value of ``quantity`` is .. code-block:: none :copyable: false - :emphasize-lines: 1, 4-6 + :emphasize-lines: 1, 4-7 Exception in thread "main" com.mongodb.MongoWriteException: Document failed validation at com.mongodb.internal.connection.ProtocolHelper.getWriteException(ProtocolHelper.java:228) @@ -94,17 +94,25 @@ as follows: .. code-block:: none :copyable: false - :emphasize-lines: 1, 5, 9 + :emphasize-lines: 1-2, 6-9, 13-16 - Exception in thread "main" com.mongodb.MongoBulkWriteException: Bulk write operation result had errors - at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:258) - ... - at BulkWriteMultipleValidationErrorsExample.main(BulkWriteMultipleValidationErrorsExample.java:30) - Caused by: com.mongodb.MongoWriteException: WriteError{code=121, message='Document failed validation', details={ operator: "$jsonSchema", schemaRules: { bsonType: "int", description: "must be an integer" }, offendingDocument: {"name":"Apple","quantity":"three"} }} - at com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) - at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) - ... 19 more - Caused by: com.mongodb.MongoWriteException: WriteError{code=121, message='Document failed validation', details={ operator: "$jsonSchema", schemaRules: { bsonType: "int", description: "must be an integer" }, offendingDocument: {"name":"Banana","quantity":"ten"} }} - at com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) - at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + Exception in thread "main" com.mongodb.MongoBulkWriteException: Bulk write + operation result had errors at + com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:258) + ... at + BulkWriteMultipleValidationErrorsExample.main(BulkWriteMultipleValidationErrorsExample.java:30) + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Apple","quantity":"three"} }} at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + at + com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + ... 19 more Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Banana","quantity":"ten"} }} at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + at + com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) ... 19 more From aef4ee580d354229094eb49587763ae1af833d56 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 14:56:51 -0400 Subject: [PATCH 11/26] DOCSP-30350 Write exceptions, reorg (cherry picked from commit 32d55d641d36696d92d7903bd4896b6c39f24e4a) --- source/crud/operation-error-handling.txt | 34 +++++++++++++++++------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 4577c3db1..b29a522c4 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -35,7 +35,7 @@ appropriate actions to either handle them or correct the error-causing code. discussions, or general technical support Write Error -~~~~~~~~~~~ +----------- If the driver encounters an error while performing a write operation, it creates an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. @@ -48,8 +48,22 @@ The ``WriteError`` type contains the following fields: .. _java_error_write_exceptions: +Write Exception Types +--------------------- + +The driver creates write exceptions when a ``WriteError`` object is created. + +The write exception object contains the following fields: + + - ``error``: the ``WriteError`` object that triggered the exception + - ``serverAddress``: the address of the server where the exception occurred + - ``errorLabels``: the server error labels, such as ``RetryableWriteError`` and ``TransientTransactionError`` + +Details on the different types of write exceptions and the error messages that +are thrown when one is created can be found below. + Write Exception ---------------- +~~~~~~~~~~~~~~~ The driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ for any errors that it encounters when performing single write operations that are @@ -83,14 +97,14 @@ either revise the document to adhere to the schema validation rules or bypass validation. Bulk Write Exception --------------------- +~~~~~~~~~~~~~~~~~~~~ If the same example were run as a bulk write operation, a `MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__ would be -thrown. A ``MongoBulkWriteException`` can contain a list of errors associated -with the same bulk write operation. For example, if you attempt to insert two -documents that violate the collection's schema, the error message would appear -as follows: +thrown. A ``MongoBulkWriteException`` contains a list of errors associated with +the same bulk write operation if more than one item caused an error. For +example, if you attempt to insert two documents that violate the collection's +schema, the driver prints the following error message: .. code-block:: none :copyable: false @@ -106,9 +120,9 @@ as follows: schemaRules: { bsonType: "int", description: "must be an integer" }, offendingDocument: {"name":"Apple","quantity":"three"} }} at com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) - at - com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) - ... 19 more Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + ... 19 more + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, message='Document failed validation', details={ operator: "$jsonSchema", schemaRules: { bsonType: "int", description: "must be an integer" }, offendingDocument: {"name":"Banana","quantity":"ten"} }} at From 71889aab121768d61b8940cda0a981bcb3560280 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 15:20:15 -0400 Subject: [PATCH 12/26] DOCSP-30350 reorg again and edit writing on some descriptions (cherry picked from commit ff68f502d4b01969dfcb7460b92c82751cf8ace9) --- source/crud/operation-error-handling.txt | 60 ++++++++++++------------ 1 file changed, 29 insertions(+), 31 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index b29a522c4..792220111 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -51,31 +51,26 @@ The ``WriteError`` type contains the following fields: Write Exception Types --------------------- -The driver creates write exceptions when a ``WriteError`` object is created. +The driver creates write exceptions when a ``WriteError`` object is created. The +driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ +for any write errors that occur when performing single write operations. If an +error is detected during a bulk write operation, a `MongoBulkWriteException +<{+core-api+}/MongoBulkWriteException.html>`__ is thrown. -The write exception object contains the following fields: - - - ``error``: the ``WriteError`` object that triggered the exception - - ``serverAddress``: the address of the server where the exception occurred - - ``errorLabels``: the server error labels, such as ``RetryableWriteError`` and ``TransientTransactionError`` - -Details on the different types of write exceptions and the error messages that -are thrown when one is created can be found below. +A ``MongoWriteException`` object contains an ``error`` field containing the +``WriteError`` object that caused it. A ``MongoBulkWriteException`` contains a +``writeErrors`` field containing a list of one or more ``WriteError`` objects +associated with the same bulk write operation. Write Exception ~~~~~~~~~~~~~~~ -The driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ for -any errors that it encounters when performing single write operations that are -not related to satisfying the write concern. The ``MongoWriteException`` type -contains the ``WriteError`` object. - -For example, the driver raises a ``MongoWriteException`` if you attempt to -insert a document into a collection that violates the collection's -schema validation rules. Suppose the collection has a rule where the -value of the ``quantity`` field must be an ``int`` type. If you -attempt to insert a document where the value of ``quantity`` is -``"three"``, the driver prints the following error message: +For example, the driver raises a ``MongoWriteException`` if you +attempt to insert a document into a collection that violates the collection's +schema validation rules. Suppose the collection has a rule where the value of +the ``quantity`` field must be an ``int`` type. If you attempt to insert a +document where the value of ``quantity`` is ``"three"``, the driver prints the +following error message: .. code-block:: none :copyable: false @@ -90,21 +85,18 @@ attempt to insert a document where the value of ``quantity`` is offendingDocument: {"name":"Apple","quantity":"three"} } } at com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) -In the preceding error message, the ``MongoWriteException`` object describes the -reason for the error, and the ``Caused by`` field provides details from the -``WriteError`` object about the failing operation. To address this error, you must -either revise the document to adhere to the schema validation rules or bypass -validation. +In the preceding error message, the ``MongoWriteException`` object provides a +high-level description of the error. The ``WriteError`` object provides details +on the failed operation, such as the schema rules and the offending document. To +address this error, you must either revise the document to adhere to the schema +validation rules or bypass validation. Bulk Write Exception ~~~~~~~~~~~~~~~~~~~~ -If the same example were run as a bulk write operation, a -`MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__ would be -thrown. A ``MongoBulkWriteException`` contains a list of errors associated with -the same bulk write operation if more than one item caused an error. For -example, if you attempt to insert two documents that violate the collection's -schema, the driver prints the following error message: +Using the previous example, if you now attempt to insert two documents that +violate the collection's schema, one with a ``quantity`` of ``three`` and another +with a ``quantity`` of ``ten``, the driver prints the following error message: .. code-block:: none :copyable: false @@ -130,3 +122,9 @@ schema, the driver prints the following error message: at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) ... 19 more + +This exception message contains a list of the two ``WriteError`` objects. The +description in the ``MongoBulkWriteException`` object is vague as +documents associated with the same bulk operation could produce different error +types. Refer to the individual ``WriteError`` objects' ``message`` fields to +determine the cause of each error. \ No newline at end of file From ad892b562ff6930de07663cca586121bf668caee Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 15:26:22 -0400 Subject: [PATCH 13/26] DOCSP30350- add quotes on strings (cherry picked from commit e30b2ed97c9e208f11c322ea727a840ec830e3ca) --- source/crud/operation-error-handling.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 792220111..2264e1923 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -95,8 +95,8 @@ Bulk Write Exception ~~~~~~~~~~~~~~~~~~~~ Using the previous example, if you now attempt to insert two documents that -violate the collection's schema, one with a ``quantity`` of ``three`` and another -with a ``quantity`` of ``ten``, the driver prints the following error message: +violate the collection's schema, one with a ``quantity`` of ``"three"`` and another +with a ``quantity`` of ``"ten"``, the driver prints the following error message: .. code-block:: none :copyable: false From 2bcc3448a4daaf291825a11cedc1a97ced72bd90 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 15:28:01 -0400 Subject: [PATCH 14/26] DOCSP-30350 toc tree naming update (cherry picked from commit e6fc4b6b4d0f4c0d2987e11118aab3275b599157) --- source/crud.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/crud.txt b/source/crud.txt index f8cf5517e..59a802221 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -19,7 +19,7 @@ CRUD Operations Collations Large File Storage with GridFS Configure Custom CRUD Settings - Write Operation Error Handling + Troubleshooting Write Exceptions - :ref:`Insert Documents ` - :ref:`Query Documents ` @@ -33,4 +33,4 @@ CRUD Operations - :ref:`Collations ` - :ref:`Large File Storage with GridFS ` - :ref:`Configure Custom CRUD Settings ` -- :ref:`Write Operation Error Handling ` +- :ref:`Troubleshooting Write Exceptions ` From 7eb677e2214e49a9de9ce559c9716702335058e0 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 15:36:38 -0400 Subject: [PATCH 15/26] DOCSP-30350 add link to schema validation page (cherry picked from commit 28c290198c6b33662683f1c193e3dc875fc97088) --- source/crud/operation-error-handling.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 2264e1923..23003857f 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -91,6 +91,8 @@ on the failed operation, such as the schema rules and the offending document. To address this error, you must either revise the document to adhere to the schema validation rules or bypass validation. +To learn more about schema validation, see :manual: in the Server Manual. + Bulk Write Exception ~~~~~~~~~~~~~~~~~~~~ @@ -127,4 +129,4 @@ This exception message contains a list of the two ``WriteError`` objects. The description in the ``MongoBulkWriteException`` object is vague as documents associated with the same bulk operation could produce different error types. Refer to the individual ``WriteError`` objects' ``message`` fields to -determine the cause of each error. \ No newline at end of file +determine the cause of each error. From dc1efbc8719a64f41d56902cc8e37e6ceee4737e Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Wed, 11 Jun 2025 15:43:11 -0400 Subject: [PATCH 16/26] DOCSP-30350 schema validation link fix (cherry picked from commit ab053b61ec5b8a04023d9784271f7fdf43fec773) --- source/crud/operation-error-handling.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt index 23003857f..b31a556da 100644 --- a/source/crud/operation-error-handling.txt +++ b/source/crud/operation-error-handling.txt @@ -91,7 +91,7 @@ on the failed operation, such as the schema rules and the offending document. To address this error, you must either revise the document to adhere to the schema validation rules or bypass validation. -To learn more about schema validation, see :manual: in the Server Manual. +To learn more about schema validation, see :manual:`Schema Validation ` in the Server Manual. Bulk Write Exception ~~~~~~~~~~~~~~~~~~~~ From a603ff93922ab420dcb027be6c3dc540df2adaf2 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Thu, 12 Jun 2025 11:43:02 -0400 Subject: [PATCH 17/26] DOCSP-30350 put troubleshooting into main pages, not separate (cherry picked from commit d4c425f0958197ef5381ab51efd1428c83f888a9) --- source/crud.txt | 2 - source/crud/bulk.txt | 57 ++++++++++ source/crud/insert.txt | 46 ++++++++ source/crud/operation-error-handling.txt | 132 ----------------------- source/includes/crud/write-error.rst | 31 ++++++ 5 files changed, 134 insertions(+), 134 deletions(-) delete mode 100644 source/crud/operation-error-handling.txt create mode 100644 source/includes/crud/write-error.rst diff --git a/source/crud.txt b/source/crud.txt index 59a802221..9f20f84af 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -19,7 +19,6 @@ CRUD Operations Collations Large File Storage with GridFS Configure Custom CRUD Settings - Troubleshooting Write Exceptions - :ref:`Insert Documents ` - :ref:`Query Documents ` @@ -33,4 +32,3 @@ CRUD Operations - :ref:`Collations ` - :ref:`Large File Storage with GridFS ` - :ref:`Configure Custom CRUD Settings ` -- :ref:`Troubleshooting Write Exceptions ` diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index 1a2477b2d..412cedc88 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -623,6 +623,63 @@ Even though the write operation inserting a document with a duplicate key result in an error, the other operations are executed because the write operation is unordered. +Troubleshooting +--------------- + +.. include:: /includes/crud/write-error.rst + +Bulk Write Exception +~~~~~~~~~~~~~~~~~~~~ + +The driver creates write exceptions when a ``WriteError`` object is created. If an +error is detected during a bulk write operation, a `MongoBulkWriteException +<{+core-api+}/MongoBulkWriteException.html>`__ is thrown. + +A ``MongoBulkWriteException`` contains a ``writeErrors`` field containing a list +of one or more ``WriteError`` objects associated with the same bulk write +operation. + +Example +''''''' + +For example, the driver raises a ``MongoBulkWriteException`` if your bulk insert +contains two documents into a collection that violate the collection's schema +validation rules. Suppose the collection has a rule where the value of the +``quantity`` field must be an ``int`` type. If your bulk insert contains a +document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of +``"ten"`, the driver prints the following error message: + +.. code-block:: none + :copyable: false + :emphasize-lines: 1-2, 6-9, 13-16 + + Exception in thread "main" com.mongodb.MongoBulkWriteException: Bulk write + operation result had errors at + com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:258) + ... at + BulkWriteMultipleValidationErrorsExample.main(BulkWriteMultipleValidationErrorsExample.java:30) + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Apple","quantity":"three"} }} at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + ... 19 more + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Banana","quantity":"ten"} }} at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + at + com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) + ... 19 more + +This exception message contains a list of the two ``WriteError`` objects. The +description in the ``MongoBulkWriteException`` object is vague as +documents associated with the same bulk operation could produce different error +types. Refer to the individual ``WriteError`` objects' ``message`` fields to +determine the cause of each error. + Additional Information ---------------------- diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 84a9cc5c6..f1dd6d6a8 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -189,6 +189,52 @@ operation and an insert many operation: insertOne() document id: BsonObjectId{value=...} insertMany() document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}} +Troubleshooting +--------------- + +.. include:: /includes/crud/write-error.rst + +Write Exception +~~~~~~~~~~~~~~~ + +The driver creates write exceptions when a ``WriteError`` object is created. The +driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ +for any write errors that occur when performing single write operations. + +A ``MongoWriteException`` object contains an ``error`` field containing the +``WriteError`` object that caused it. + +Example +''''''' + +For example, the driver raises a ``MongoWriteException`` if you +attempt to insert a document into a collection that violates the collection's +schema validation rules. Suppose the collection has a rule where the value of +the ``quantity`` field must be an ``int`` type. If you attempt to insert a +document where the value of ``quantity`` is ``"three"``, the driver prints the +following error message: + +.. code-block:: none + :copyable: false + :emphasize-lines: 1, 4-7 + + Exception in thread "main" com.mongodb.MongoWriteException: Document failed validation at + com.mongodb.internal.connection.ProtocolHelper.getWriteException(ProtocolHelper.java:228) + ... + Caused by: com.mongodb.MongoWriteException: WriteError{code=121, + message='Document failed validation', details={ operator: "$jsonSchema", + schemaRules: { bsonType: "int", description: "must be an integer" }, + offendingDocument: {"name":"Apple","quantity":"three"} } } at + com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) + +In the preceding error message, the ``MongoWriteException`` object provides a +high-level description of the error. The ``WriteError`` object provides details +on the failed operation, such as the schema rules and the offending document. To +address this error, you must either revise the document to adhere to the schema +validation rules or bypass validation. + +To learn more about schema validation, see :manual:`Schema Validation ` in the Server Manual. + Additional Information ---------------------- diff --git a/source/crud/operation-error-handling.txt b/source/crud/operation-error-handling.txt deleted file mode 100644 index b31a556da..000000000 --- a/source/crud/operation-error-handling.txt +++ /dev/null @@ -1,132 +0,0 @@ -.. _java-operation-errors: - -================================ -Troubleshooting Write Exceptions -================================ - -.. meta:: - :description: Understand how to handle write exceptions in the MongoDB Java Sync Driver, including error types like WriteError and BulkWriteError. - -.. contents:: - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -This page describes write exceptions you might encounter when -using the {+driver-long+} to perform MongoDB write operations. Once you -understand the types of write exceptions that the driver raises, you can take -appropriate actions to either handle them or correct the error-causing code. - -.. note:: - - This page addresses only write exception handling. If you encounter - any other issues with MongoDB or the driver, visit the following - resources: - - - :ref:`java-connection-troubleshooting` for potential solutions to issues - you might encounter when connecting to a MongoDB deployment - - :ref:`java-issues-and-help` page for information about reporting bugs, - contributing to the driver, and finding more resources - - :community-forum:`MongoDB Community Forums ` for questions, - discussions, or general technical support - -Write Error ------------ - -If the driver encounters an error while performing a write operation, it -creates an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. - -The ``WriteError`` type contains the following fields: - - - ``code``: the code associated with the error - - ``message``: a message explaining the error - - ``details``: an optional field containing details associated with the error - -.. _java_error_write_exceptions: - -Write Exception Types ---------------------- - -The driver creates write exceptions when a ``WriteError`` object is created. The -driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ -for any write errors that occur when performing single write operations. If an -error is detected during a bulk write operation, a `MongoBulkWriteException -<{+core-api+}/MongoBulkWriteException.html>`__ is thrown. - -A ``MongoWriteException`` object contains an ``error`` field containing the -``WriteError`` object that caused it. A ``MongoBulkWriteException`` contains a -``writeErrors`` field containing a list of one or more ``WriteError`` objects -associated with the same bulk write operation. - -Write Exception -~~~~~~~~~~~~~~~ - -For example, the driver raises a ``MongoWriteException`` if you -attempt to insert a document into a collection that violates the collection's -schema validation rules. Suppose the collection has a rule where the value of -the ``quantity`` field must be an ``int`` type. If you attempt to insert a -document where the value of ``quantity`` is ``"three"``, the driver prints the -following error message: - -.. code-block:: none - :copyable: false - :emphasize-lines: 1, 4-7 - - Exception in thread "main" com.mongodb.MongoWriteException: Document failed validation at - com.mongodb.internal.connection.ProtocolHelper.getWriteException(ProtocolHelper.java:228) - ... - Caused by: com.mongodb.MongoWriteException: WriteError{code=121, - message='Document failed validation', details={ operator: "$jsonSchema", - schemaRules: { bsonType: "int", description: "must be an integer" }, - offendingDocument: {"name":"Apple","quantity":"three"} } } at - com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) - -In the preceding error message, the ``MongoWriteException`` object provides a -high-level description of the error. The ``WriteError`` object provides details -on the failed operation, such as the schema rules and the offending document. To -address this error, you must either revise the document to adhere to the schema -validation rules or bypass validation. - -To learn more about schema validation, see :manual:`Schema Validation ` in the Server Manual. - -Bulk Write Exception -~~~~~~~~~~~~~~~~~~~~ - -Using the previous example, if you now attempt to insert two documents that -violate the collection's schema, one with a ``quantity`` of ``"three"`` and another -with a ``quantity`` of ``"ten"``, the driver prints the following error message: - -.. code-block:: none - :copyable: false - :emphasize-lines: 1-2, 6-9, 13-16 - - Exception in thread "main" com.mongodb.MongoBulkWriteException: Bulk write - operation result had errors at - com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:258) - ... at - BulkWriteMultipleValidationErrorsExample.main(BulkWriteMultipleValidationErrorsExample.java:30) - Caused by: com.mongodb.MongoWriteException: WriteError{code=121, - message='Document failed validation', details={ operator: "$jsonSchema", - schemaRules: { bsonType: "int", description: "must be an integer" }, - offendingDocument: {"name":"Apple","quantity":"three"} }} at - com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) - at com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) - ... 19 more - Caused by: com.mongodb.MongoWriteException: WriteError{code=121, - message='Document failed validation', details={ operator: "$jsonSchema", - schemaRules: { bsonType: "int", description: "must be an integer" }, - offendingDocument: {"name":"Banana","quantity":"ten"} }} at - com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) - at - com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) - ... 19 more - -This exception message contains a list of the two ``WriteError`` objects. The -description in the ``MongoBulkWriteException`` object is vague as -documents associated with the same bulk operation could produce different error -types. Refer to the individual ``WriteError`` objects' ``message`` fields to -determine the cause of each error. diff --git a/source/includes/crud/write-error.rst b/source/includes/crud/write-error.rst new file mode 100644 index 000000000..e812316a8 --- /dev/null +++ b/source/includes/crud/write-error.rst @@ -0,0 +1,31 @@ +.. _java_write_error: + +This section describes write exceptions you might encounter when +using the {+driver-long+} to perform MongoDB write operations. Once you +understand the types of write exceptions that the driver raises, you can take +appropriate actions to either handle them or correct the error-causing code. + +.. note:: + + This page addresses only write exception handling. If you encounter + any other issues with MongoDB or the driver, visit the following + resources: + + - :ref:`java-connection-troubleshooting` for potential solutions to issues + you might encounter when connecting to a MongoDB deployment + - :ref:`java-issues-and-help` page for information about reporting bugs, + contributing to the driver, and finding more resources + - :community-forum:`MongoDB Community Forums ` for questions, + discussions, or general technical support + +Write Error +~~~~~~~~~~~ + +If the driver encounters an error while performing a write operation, it +creates an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. + +The ``WriteError`` type contains the following fields: + + - ``code``: the code associated with the error + - ``message``: a message explaining the error + - ``details``: an optional field containing details associated with the error \ No newline at end of file From 91d46f33afa57dd93858b06167270ded1acd2856 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Thu, 12 Jun 2025 12:00:39 -0400 Subject: [PATCH 18/26] DOCSP-30350 Adding descriptions and editing (cherry picked from commit 0bead5f4d847d3bb08ffc86b55d89534263ccc43) --- source/crud/bulk.txt | 20 +++++++++++++------- source/crud/insert.txt | 4 +++- source/includes/crud/write-error.rst | 10 +++++----- 3 files changed, 21 insertions(+), 13 deletions(-) diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index 412cedc88..6c463c4fa 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -623,6 +623,8 @@ Even though the write operation inserting a document with a duplicate key result in an error, the other operations are executed because the write operation is unordered. +.. _java-bulk-insert-troubleshooting: + Troubleshooting --------------- @@ -631,7 +633,7 @@ Troubleshooting Bulk Write Exception ~~~~~~~~~~~~~~~~~~~~ -The driver creates write exceptions when a ``WriteError`` object is created. If an +The driver creates a write exception when a ``WriteError`` object is created. If an error is detected during a bulk write operation, a `MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__ is thrown. @@ -643,7 +645,7 @@ Example ''''''' For example, the driver raises a ``MongoBulkWriteException`` if your bulk insert -contains two documents into a collection that violate the collection's schema +contains two documents that violate the collection's schema validation rules. Suppose the collection has a rule where the value of the ``quantity`` field must be an ``int`` type. If your bulk insert contains a document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of @@ -674,11 +676,15 @@ document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) ... 19 more -This exception message contains a list of the two ``WriteError`` objects. The -description in the ``MongoBulkWriteException`` object is vague as -documents associated with the same bulk operation could produce different error -types. Refer to the individual ``WriteError`` objects' ``message`` fields to -determine the cause of each error. + +In the preceding error message, the ``MongoBulkWriteException`` object provides +a vague description of the error, as documents associated with the same bulk +operation could produce different error types. Instead, refer to the +``WriteError`` objects' ``message`` fields to determine the cause of each error. +Refer to the ``WriteError`` objects' ``details`` field for more specific +information, such as the schema rules and the offending documents. To address +this error, you must either revise the document to adhere to the schema +validation rules or bypass validation. Additional Information ---------------------- diff --git a/source/crud/insert.txt b/source/crud/insert.txt index f1dd6d6a8..ed630ec12 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -189,6 +189,8 @@ operation and an insert many operation: insertOne() document id: BsonObjectId{value=...} insertMany() document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}} +.. _java-insert-troubleshooting: + Troubleshooting --------------- @@ -197,7 +199,7 @@ Troubleshooting Write Exception ~~~~~~~~~~~~~~~ -The driver creates write exceptions when a ``WriteError`` object is created. The +The driver creates a write exception when a ``WriteError`` object is created. The driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ for any write errors that occur when performing single write operations. diff --git a/source/includes/crud/write-error.rst b/source/includes/crud/write-error.rst index e812316a8..c326f0725 100644 --- a/source/includes/crud/write-error.rst +++ b/source/includes/crud/write-error.rst @@ -1,13 +1,13 @@ .. _java_write_error: -This section describes write exceptions you might encounter when -using the {+driver-long+} to perform MongoDB write operations. Once you -understand the types of write exceptions that the driver raises, you can take -appropriate actions to either handle them or correct the error-causing code. +This section explains write exceptions you might encounter when using the +{+driver-long+} to perform MongoDB write operations. Once you learn how to +understand the write exceptions that the driver raises, you can take appropriate +actions to either handle them or correct the error-causing code. .. note:: - This page addresses only write exception handling. If you encounter + This section addresses only write exception handling. If you encounter any other issues with MongoDB or the driver, visit the following resources: From fab3104dbf5c039dd996e13c5a47013e463f9c31 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Thu, 12 Jun 2025 13:22:40 -0400 Subject: [PATCH 19/26] DOCSP-30350 fixing example headings and final edits (cherry picked from commit 2afc1d1d15693dc956c33e057f958c4951ffbf4f) --- source/crud/bulk.txt | 8 ++++---- source/crud/insert.txt | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index 6c463c4fa..090acf901 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -633,16 +633,16 @@ Troubleshooting Bulk Write Exception ~~~~~~~~~~~~~~~~~~~~ -The driver creates a write exception when a ``WriteError`` object is created. If an +The driver creates a write exception when it creates a ``WriteError`` object. If an error is detected during a bulk write operation, a `MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__ is thrown. -A ``MongoBulkWriteException`` contains a ``writeErrors`` field containing a list -of one or more ``WriteError`` objects associated with the same bulk write +A ``MongoBulkWriteException`` contains a ``writeErrors`` field consisting of a +list of one or more ``WriteError`` objects associated with the same bulk write operation. Example -''''''' +``````` For example, the driver raises a ``MongoBulkWriteException`` if your bulk insert contains two documents that violate the collection's schema diff --git a/source/crud/insert.txt b/source/crud/insert.txt index ed630ec12..3220392eb 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -199,15 +199,15 @@ Troubleshooting Write Exception ~~~~~~~~~~~~~~~ -The driver creates a write exception when a ``WriteError`` object is created. The +The driver creates a write exception when it creates a ``WriteError`` object. The driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ for any write errors that occur when performing single write operations. -A ``MongoWriteException`` object contains an ``error`` field containing the +A ``MongoWriteException`` object has an ``error`` field containing the ``WriteError`` object that caused it. Example -''''''' +``````` For example, the driver raises a ``MongoWriteException`` if you attempt to insert a document into a collection that violates the collection's From f0fc822e496a6ec243d3e0a0e86a6206a16d2f11 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Thu, 12 Jun 2025 13:33:04 -0400 Subject: [PATCH 20/26] DOCSP-30350 making vocab consistent, active voice (cherry picked from commit 2922c977ffbec5cbc485a1b7ebcb00939fc00810) --- source/crud/bulk.txt | 6 +++--- source/crud/insert.txt | 4 ++-- source/includes/crud/write-error.rst | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index 090acf901..d0ffcf1b7 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -634,8 +634,8 @@ Bulk Write Exception ~~~~~~~~~~~~~~~~~~~~ The driver creates a write exception when it creates a ``WriteError`` object. If an -error is detected during a bulk write operation, a `MongoBulkWriteException -<{+core-api+}/MongoBulkWriteException.html>`__ is thrown. +error is detected during a bulk write operation, the driver throws a `MongoBulkWriteException +<{+core-api+}/MongoBulkWriteException.html>`__. A ``MongoBulkWriteException`` contains a ``writeErrors`` field consisting of a list of one or more ``WriteError`` objects associated with the same bulk write @@ -644,7 +644,7 @@ operation. Example ``````` -For example, the driver raises a ``MongoBulkWriteException`` if your bulk insert +For example, the driver throws a ``MongoBulkWriteException`` if your bulk insert contains two documents that violate the collection's schema validation rules. Suppose the collection has a rule where the value of the ``quantity`` field must be an ``int`` type. If your bulk insert contains a diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 3220392eb..8adf56974 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -200,7 +200,7 @@ Write Exception ~~~~~~~~~~~~~~~ The driver creates a write exception when it creates a ``WriteError`` object. The -driver raises a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ +driver throws a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ for any write errors that occur when performing single write operations. A ``MongoWriteException`` object has an ``error`` field containing the @@ -209,7 +209,7 @@ A ``MongoWriteException`` object has an ``error`` field containing the Example ``````` -For example, the driver raises a ``MongoWriteException`` if you +For example, the driver throws a ``MongoWriteException`` if you attempt to insert a document into a collection that violates the collection's schema validation rules. Suppose the collection has a rule where the value of the ``quantity`` field must be an ``int`` type. If you attempt to insert a diff --git a/source/includes/crud/write-error.rst b/source/includes/crud/write-error.rst index c326f0725..e51dcbe35 100644 --- a/source/includes/crud/write-error.rst +++ b/source/includes/crud/write-error.rst @@ -22,7 +22,7 @@ Write Error ~~~~~~~~~~~ If the driver encounters an error while performing a write operation, it -creates an error of the `WriteError <{+core-api+}/WriteError.html>`__ type. +creates an error object of the `WriteError <{+core-api+}/WriteError.html>`__ type. The ``WriteError`` type contains the following fields: From 5b539a6bedb2be1f44d5e3f7b81b12eed4e33bed Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Thu, 12 Jun 2025 14:01:34 -0400 Subject: [PATCH 21/26] DOCSP-30350 fix typo (cherry picked from commit 140c02d55b3adc8544f68fb95739ca4ec6b48b0a) --- source/crud/bulk.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index d0ffcf1b7..5e637893d 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -649,7 +649,7 @@ contains two documents that violate the collection's schema validation rules. Suppose the collection has a rule where the value of the ``quantity`` field must be an ``int`` type. If your bulk insert contains a document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of -``"ten"`, the driver prints the following error message: +``"ten"``, the driver prints the following error message: .. code-block:: none :copyable: false From dc22ad5f463c2482eb52b4bb0ba6209f88144ae3 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 12:17:51 -0400 Subject: [PATCH 22/26] DOCSP-30350 adding suggestions and API doc links (cherry picked from commit 763949d30c42349e6ed634e9622837fa8bac5cce) --- source/crud/bulk.txt | 42 ++++++++----------------- source/crud/insert.txt | 46 +++++++++++----------------- source/includes/crud/write-error.rst | 31 ------------------- 3 files changed, 30 insertions(+), 89 deletions(-) delete mode 100644 source/includes/crud/write-error.rst diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index 5e637893d..3241f2db6 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -628,28 +628,16 @@ unordered. Troubleshooting --------------- -.. include:: /includes/crud/write-error.rst +If the driver encounters an error during a bulk write operation, the driver +throws a `MongoBulkWriteException +<{+core-api+}/MongoBulkWriteException.html>`__. A ``MongoBulkWriteException`` +contains a ``writeErrors`` field consisting of a list of one or more +``WriteError`` objects associated with the same bulk write operation. -Bulk Write Exception -~~~~~~~~~~~~~~~~~~~~ - -The driver creates a write exception when it creates a ``WriteError`` object. If an -error is detected during a bulk write operation, the driver throws a `MongoBulkWriteException -<{+core-api+}/MongoBulkWriteException.html>`__. - -A ``MongoBulkWriteException`` contains a ``writeErrors`` field consisting of a -list of one or more ``WriteError`` objects associated with the same bulk write -operation. - -Example -``````` - -For example, the driver throws a ``MongoBulkWriteException`` if your bulk insert -contains two documents that violate the collection's schema -validation rules. Suppose the collection has a rule where the value of the -``quantity`` field must be an ``int`` type. If your bulk insert contains a -document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of -``"ten"``, the driver prints the following error message: +Consider a collection that has a rule where the value of the ``quantity`` field +must be an ``int`` type. In the following example, a ``MongoBulkWriteException`` +is thrown when when you attempt to insert a document with a ``quantity`` field +value of ``"three"`` and another with a ``quantity`` field value of ``"ten"``. .. code-block:: none :copyable: false @@ -676,15 +664,8 @@ document with a ``quantity`` of ``"three"`` and another with a ``quantity`` of com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) ... 19 more - -In the preceding error message, the ``MongoBulkWriteException`` object provides -a vague description of the error, as documents associated with the same bulk -operation could produce different error types. Instead, refer to the -``WriteError`` objects' ``message`` fields to determine the cause of each error. -Refer to the ``WriteError`` objects' ``details`` field for more specific -information, such as the schema rules and the offending documents. To address -this error, you must either revise the document to adhere to the schema -validation rules or bypass validation. +To learn more about the ``MongoBulkWriteException`` and ``WriteError`` types, +see MongoBulkWriteException and WriteError in the API documentation. Additional Information ---------------------- @@ -700,6 +681,7 @@ MongoCollection - `bulkWrite() <{+driver-api+}/MongoCollection.html#bulkWrite(com.mongodb.client.ClientSession,java.util.List)>`__ - `BulkWriteOptions <{+core-api+}/client/model/BulkWriteOptions.html>`__ +- `WriteError <{+core-api+}/WriteError.html>`__ - `MongoBulkWriteException <{+core-api+}/MongoBulkWriteException.html>`__ MongoClient diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 8adf56974..b4e32ffda 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -15,7 +15,7 @@ Insert Operations .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol Overview @@ -194,27 +194,15 @@ operation and an insert many operation: Troubleshooting --------------- -.. include:: /includes/crud/write-error.rst +The driver throws a `MongoWriteException +<{+core-api+}/MongoWriteException.html>`__ for any write errors that occur when +performing single write operations. A ``MongoWriteException`` object has an +``error`` field containing the ``WriteError`` object that caused it. -Write Exception -~~~~~~~~~~~~~~~ - -The driver creates a write exception when it creates a ``WriteError`` object. The -driver throws a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ -for any write errors that occur when performing single write operations. - -A ``MongoWriteException`` object has an ``error`` field containing the -``WriteError`` object that caused it. - -Example -``````` - -For example, the driver throws a ``MongoWriteException`` if you -attempt to insert a document into a collection that violates the collection's -schema validation rules. Suppose the collection has a rule where the value of -the ``quantity`` field must be an ``int`` type. If you attempt to insert a -document where the value of ``quantity`` is ``"three"``, the driver prints the -following error message: +Consider a collection with a rule where the value of the ``quantity`` field must +be an ``int`` type. In the following example, a ``MongoBulkWriteException`` is +thrown if you attempt to insert a document where the value of ``quantity`` is +``"three"``. .. code-block:: none :copyable: false @@ -229,13 +217,9 @@ following error message: offendingDocument: {"name":"Apple","quantity":"three"} } } at com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) -In the preceding error message, the ``MongoWriteException`` object provides a -high-level description of the error. The ``WriteError`` object provides details -on the failed operation, such as the schema rules and the offending document. To -address this error, you must either revise the document to adhere to the schema -validation rules or bypass validation. - -To learn more about schema validation, see :manual:`Schema Validation ` in the Server Manual. +To learn more about the ``MongoWriteException`` and ``WriteError`` types, +see MongoWriteException and WriteError in the API documentation. To learn +more about schema validation, see Schema Validation in Additional Information. Additional Information ---------------------- @@ -250,8 +234,14 @@ For more information about the methods and classes used to insert documents, see - `insertMany() <{+driver-api+}/MongoCollection.html#insertMany(java.util.List)>`__ - `InsertManyResult <{+core-api+}/client/result/InsertManyResult.html>`__ +For more information about the error types discussed in the Troubleshooting section, see the following API documentation: + +- `WriteError <{+core-api+}/WriteError.html>`__ +- `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ + Server Manual Entries ~~~~~~~~~~~~~~~~~~~~~ - :manual:`db.collection.insertOne() ` - :manual:`db.collection.insertMany() ` +- :manual:`Schema Validation ` diff --git a/source/includes/crud/write-error.rst b/source/includes/crud/write-error.rst deleted file mode 100644 index e51dcbe35..000000000 --- a/source/includes/crud/write-error.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _java_write_error: - -This section explains write exceptions you might encounter when using the -{+driver-long+} to perform MongoDB write operations. Once you learn how to -understand the write exceptions that the driver raises, you can take appropriate -actions to either handle them or correct the error-causing code. - -.. note:: - - This section addresses only write exception handling. If you encounter - any other issues with MongoDB or the driver, visit the following - resources: - - - :ref:`java-connection-troubleshooting` for potential solutions to issues - you might encounter when connecting to a MongoDB deployment - - :ref:`java-issues-and-help` page for information about reporting bugs, - contributing to the driver, and finding more resources - - :community-forum:`MongoDB Community Forums ` for questions, - discussions, or general technical support - -Write Error -~~~~~~~~~~~ - -If the driver encounters an error while performing a write operation, it -creates an error object of the `WriteError <{+core-api+}/WriteError.html>`__ type. - -The ``WriteError`` type contains the following fields: - - - ``code``: the code associated with the error - - ``message``: a message explaining the error - - ``details``: an optional field containing details associated with the error \ No newline at end of file From 00723b15644ec4e7c4aee48edf8ff811e1a465bf Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 12:28:35 -0400 Subject: [PATCH 23/26] DOCSP-30350 small tweaks to punctuation and wording (cherry picked from commit 2b7584f357a15ec9ad7f337a47e5763726cfab5b) --- source/crud/bulk.txt | 6 +++--- source/crud/insert.txt | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index 3241f2db6..c7e1c1be4 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -629,8 +629,8 @@ Troubleshooting --------------- If the driver encounters an error during a bulk write operation, the driver -throws a `MongoBulkWriteException -<{+core-api+}/MongoBulkWriteException.html>`__. A ``MongoBulkWriteException`` +throws a `MongoBulkWriteException. +<{+core-api+}/MongoBulkWriteException.html>`__ A ``MongoBulkWriteException`` contains a ``writeErrors`` field consisting of a list of one or more ``WriteError`` objects associated with the same bulk write operation. @@ -665,7 +665,7 @@ value of ``"three"`` and another with a ``quantity`` field value of ``"ten"``. ... 19 more To learn more about the ``MongoBulkWriteException`` and ``WriteError`` types, -see MongoBulkWriteException and WriteError in the API documentation. +see MongoBulkWriteException and WriteError in the API Documentation section. Additional Information ---------------------- diff --git a/source/crud/insert.txt b/source/crud/insert.txt index b4e32ffda..e09710430 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -218,8 +218,8 @@ thrown if you attempt to insert a document where the value of ``quantity`` is com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) To learn more about the ``MongoWriteException`` and ``WriteError`` types, -see MongoWriteException and WriteError in the API documentation. To learn -more about schema validation, see Schema Validation in Additional Information. +see MongoWriteException and WriteError in the API Documentation section. To learn +more about schema validation, see Schema Validation in the Server Manual Entries section. Additional Information ---------------------- From 2587bb413fe3d525ba745ab7eaaa23cae7f894e0 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 15:06:29 -0400 Subject: [PATCH 24/26] DOCSP-30350 final edits (cherry picked from commit cc021ca678345370e4af07c582afd2f372373150) --- source/crud/bulk.txt | 13 +++++++------ source/crud/insert.txt | 14 ++++++++------ 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index c7e1c1be4..b59d18503 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -628,6 +628,9 @@ unordered. Troubleshooting --------------- +Bulk Write Exception +~~~~~~~~~~~~~~~~~~~~ + If the driver encounters an error during a bulk write operation, the driver throws a `MongoBulkWriteException. <{+core-api+}/MongoBulkWriteException.html>`__ A ``MongoBulkWriteException`` @@ -635,9 +638,10 @@ contains a ``writeErrors`` field consisting of a list of one or more ``WriteError`` objects associated with the same bulk write operation. Consider a collection that has a rule where the value of the ``quantity`` field -must be an ``int`` type. In the following example, a ``MongoBulkWriteException`` -is thrown when when you attempt to insert a document with a ``quantity`` field -value of ``"three"`` and another with a ``quantity`` field value of ``"ten"``. +must be an ``int`` type. In the following example, the driver throws a +``MongoBulkWriteException`` when you attempt to insert a document with a +``quantity`` field value of ``"three"`` and another with a ``quantity`` field +value of ``"ten"``. .. code-block:: none :copyable: false @@ -664,9 +668,6 @@ value of ``"three"`` and another with a ``quantity`` field value of ``"ten"``. com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) ... 19 more -To learn more about the ``MongoBulkWriteException`` and ``WriteError`` types, -see MongoBulkWriteException and WriteError in the API Documentation section. - Additional Information ---------------------- diff --git a/source/crud/insert.txt b/source/crud/insert.txt index e09710430..451394a31 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -194,15 +194,18 @@ operation and an insert many operation: Troubleshooting --------------- +Write Exception +~~~~~~~~~~~~~~~ + The driver throws a `MongoWriteException <{+core-api+}/MongoWriteException.html>`__ for any write errors that occur when performing single write operations. A ``MongoWriteException`` object has an ``error`` field containing the ``WriteError`` object that caused it. Consider a collection with a rule where the value of the ``quantity`` field must -be an ``int`` type. In the following example, a ``MongoBulkWriteException`` is -thrown if you attempt to insert a document where the value of ``quantity`` is -``"three"``. +be an ``int`` type. In the following example, the driver throws a +``MongoWriteException`` if you attempt to insert a document where the value of +``quantity`` is ``"three"``. .. code-block:: none :copyable: false @@ -217,9 +220,8 @@ thrown if you attempt to insert a document where the value of ``quantity`` is offendingDocument: {"name":"Apple","quantity":"three"} } } at com.mongodb.internal.connection.WriteResultHelper.createWriteException(WriteResultHelper.java:50) -To learn more about the ``MongoWriteException`` and ``WriteError`` types, -see MongoWriteException and WriteError in the API Documentation section. To learn -more about schema validation, see Schema Validation in the Server Manual Entries section. +To learn more about schema validation, see Schema Validation in the Server +Manual Entries section. Additional Information ---------------------- From b763e2a61ccdc2be7744ef470c59bea5ff33264d Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Fri, 13 Jun 2025 15:18:04 -0400 Subject: [PATCH 25/26] DOCSP-30350 add schema val link to bulk (cherry picked from commit dd420c23d33227bbc20c8fbea75ab08c58a31807) --- source/crud/bulk.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index b59d18503..da72b76a6 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -668,6 +668,9 @@ value of ``"ten"``. com.mongodb.internal.connection.ProtocolHelper.getBulkWriteException(ProtocolHelper.java:254) ... 19 more +To learn more about schema validation, see Schema Validation in the Server +Manual Entries section. + Additional Information ---------------------- @@ -697,3 +700,4 @@ Server Manual Entries - :manual:`MongoCollection.bulkWrite() ` - :manual:`MongoClient.bulkWrite() ` +- :manual:`Schema Validation ` From dab944446020c95c89c3a029d66080bcfc376e42 Mon Sep 17 00:00:00 2001 From: Melanie Ballard Date: Tue, 17 Jun 2025 12:01:22 -0400 Subject: [PATCH 26/26] DOCSP-30350 minor change tech reivew clarify schema validation (cherry picked from commit 4abbd49bca3de9b283156ee54bfc5e9dd1a621a9) --- source/crud/bulk.txt | 8 ++++---- source/crud/insert.txt | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/source/crud/bulk.txt b/source/crud/bulk.txt index da72b76a6..8af873102 100644 --- a/source/crud/bulk.txt +++ b/source/crud/bulk.txt @@ -637,10 +637,10 @@ throws a `MongoBulkWriteException. contains a ``writeErrors`` field consisting of a list of one or more ``WriteError`` objects associated with the same bulk write operation. -Consider a collection that has a rule where the value of the ``quantity`` field -must be an ``int`` type. In the following example, the driver throws a -``MongoBulkWriteException`` when you attempt to insert a document with a -``quantity`` field value of ``"three"`` and another with a ``quantity`` field +Consider a collection that has a schema validation rule where the value of the +``quantity`` field must be an ``int`` type. In the following example, the driver +throws a ``MongoBulkWriteException`` when you attempt to insert a document with +a ``quantity`` field value of ``"three"`` and another with a ``quantity`` field value of ``"ten"``. .. code-block:: none diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 451394a31..92fb1e96f 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -202,10 +202,10 @@ The driver throws a `MongoWriteException performing single write operations. A ``MongoWriteException`` object has an ``error`` field containing the ``WriteError`` object that caused it. -Consider a collection with a rule where the value of the ``quantity`` field must -be an ``int`` type. In the following example, the driver throws a -``MongoWriteException`` if you attempt to insert a document where the value of -``quantity`` is ``"three"``. +Consider a collection that has a schema validation rule where the value of the +``quantity`` field must be an ``int`` type. In the following example, the driver +throws a ``MongoWriteException`` if you attempt to insert a document where the +value of ``quantity`` is ``"three"``. .. code-block:: none :copyable: false