DOCS-1143 DOCS-425 mongos troubleshooting

source/includes/toc-sharded-cluster-tutorials-landing.yaml

@@ -13,4 +13,9 @@ file: /administration/sharded-cluster-data
 description: |
   Practices that address common issues in managing large sharded data
   sets.
+---
+file: /tutorial/troubleshoot-sharded-clusters
+description: |
+  Describes solutions to certain issues encountered on sharded clusters.
+  For additional diagnostic information, see :doc:`/faq/diagnostics`.
 ...

source/includes/toc-spec-sharded-cluster-tutorials-landing.yaml

@@ -30,4 +30,6 @@ files:
     level: 2
   - file: /tutorial/shard-gridfs-data
     level: 2
+  - file: /tutorial/troubleshoot-sharded-clusters
+    level: 1
 ...

source/tutorial/deploy-shard-cluster.txt

@@ -107,6 +107,15 @@ You would issue the following command:
 
    mongos --configdb cfg0.example.net:27019,cfg1.example.net:27019,cfg2.example.net:27019
 
+Each :program:`mongos` in the sharded cluster must use the same
+:setting:`configdb` string, with identical host names listed in identical
+order.
+
+If you start a :program:`mongos` instance with a string that does not exactly
+match the string used by the other :program:`mongos` instances in the cluster, the
+:program:`mongos` fails and you receive the
+:ref:`config-database-string-error` error.
+
 .. _sharding-setup-add-shards:
 
 Add Shards to the Cluster

source/tutorial/troubleshoot-sharded-clusters.txt

@@ -0,0 +1,52 @@
+=============================
+Troubleshoot Sharded Clusters
+=============================
+
+.. default-domain:: mongodb
+
+This section provides solutions to issues encountered on
+:term:`sharded clusters <sharded cluster>`.
+
+.. _config-database-string-error:
+
+Config Database String Error
+----------------------------
+
+.. DOCS-1143
+
+Start all :program:`mongos` instances in a sharded cluster with an identical
+:setting:`configdb` string. If a :program:`mongos` instance tries to
+connect to the sharded cluster with a :setting:`configdb` string that
+does not *exactly* match the string used by the other :program:`mongos`
+instances, including the order of the hosts, the following errors occur:
+
+.. code-block:: none
+
+   could not initialize sharding on connection
+
+And:
+
+.. code-block:: none
+
+   mongos specified a different config database string
+
+To solve the issue, restart the :program:`mongos` with the correct
+string.
+
+Cursor Fails Because of Stale Config Data
+-----------------------------------------
+
+.. DOCS-425
+
+A query issues the following warning when one or more of the
+:program:`mongos` instances has not yet updated its cache of the
+cluster's metadata from the :term:`config database`:
+
+.. code-block:: none
+
+   could not initialize cursor across all shards because : stale config detected
+
+This warning *should* not propagate back to your application. The warning
+will repeat until all the :program:`mongos` instances refresh their
+caches. To force an instance to refresh its cache, run the
+:dbcommand:`flushRouterConfig` command.