DOCSP-26369: FAQ entry for invalid bson field name (#420)

* DOCSP-26369: Invalid BSON field name

Author: Chris Cho

source/faq.txt

@@ -4,8 +4,6 @@
 FAQ
 ===
 
-.. default-domain:: mongodb
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -148,6 +146,52 @@ When ``MongoClient.close()`` is called by any thread, the driver
 closes all idle sockets and closes all sockets that are in
 use as they are returned to the pool.
 
+
+How do I prevent the "IllegalArgumentException: Invalid BSON field name" error?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your application may throw this exception if you pass an incorrectly formatted
+document to an operation and you are using a driver version v4.7 or earlier.
+
+.. note::
+
+   In driver versions v4.8 and later, this error message was replaced by one
+   that includes more specific details on what was incorrectly formatted.
+
+For example, the driver throws this error when you call an update operation
+and incorrectly omit the update operator as shown in the following code
+example:
+
+.. code-block:: java
+   :emphasize-lines: 4
+   :copyable: false
+
+   // incorrectly formatted update document
+   collection.updateOne(
+       new Document().append("name", "fizz"),
+       new Document().append("name", "buzz")
+   );
+
+To avoid this error, use the builder class for the appropriate operation.
+The driver offers builder classes to create syntactically correct BSON for
+MongoDB operations. The prior example can be correctly expressed using
+the builder classes as shown in the following code example:
+
+.. code-block:: java
+   :emphasize-lines: 7
+   :copyable: false
+
+   // Builder class imports
+   import static com.mongodb.client.model.Filters.*;
+   import static com.mongodb.client.model.Updates.*;
+
+   // ...
+
+   collection.updateOne(eq("name", "fizz"), set("name", "buzz"));
+
+To learn more about the available builders classes, see the :ref:`<java-builders>` documentation.
+
+
 How do I prevent the "IllegalStateException: state should be: open" error?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -177,6 +221,7 @@ after any code that calls ``close()`` on it.
    To learn more about accessing MongoDB from Spring Boot, see
    `Spring Boot and MongoDB <https://www.mongodb.com/compatibility/spring-boot>`__.
 
+
 POJOs
 -----
 

source/fundamentals/builders.txt

@@ -1,3 +1,5 @@
+.. _java-builders:
+
 ========
 Builders
 ========