> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# checkMetadataConsistency (database command)

## Definition

Performs a series of consistency checks on sharding metadata for a cluster, database, or collection.  The command returns a cursor with either all or a batch of the [inconsistency results](https://www.mongodb.com/docs/manual/reference/inconsistency-type.md#std-label-inconsistency-types) found.

**Tip:**

In [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh), this command can also be run through the [`db.checkMetadataConsistency()`](https://www.mongodb.com/docs/manual/reference/method/db.checkmetadataconsistency.md#mongodb-method-db.checkMetadataConsistency),
[`db.collection.checkMetadataConsistency()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.checkmetadataconsistency.md#mongodb-method-db.collection.checkMetadataConsistency), or
[`sh.checkMetadataConsistency()`](https://www.mongodb.com/docs/manual/reference/method/sh.checkmetadataconsistency.md#mongodb-method-sh.checkMetadataConsistency) helper methods.

Helper methods are convenient for [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh) users, but they may not return the same level of information as database commands.  In cases where the convenience is not needed or the additional return fields are required, use the database command.

Run this command after major maintenance operations, such as upgrades and downgrades, to check the state of the catalog.

By default, the command does not check indexes for consistency across the shards.  To check indexes, set the `checkIndexes` option.

**New in version 7.0**

## Compatibility

This command is available in deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

**Note:**

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

**Note:**

The `checkMetadataConsistency` command is executable only when connecting to `mongos`. `mongod` does not support this command.

## Syntax

- To check the entire cluster for sharding metadata inconsistencies, run the command from the `admin` database.

  ```javascript
  db.adminCommand( {
     checkMetadataConsistency: 1
  } )
  ```

- To check the database for sharding metadata inconsistencies, run the command from the database context:

  ```javascript
  use cars
  db.runCommand( {
     checkMetadataConsistency: 1
  } )
  ```

- To check a collection for sharding metadata inconsistencies, run the command with the collection name:

  ```javascript
  use library
  db.runCommand( {
     checkMetadataConsistency: "authors",
  } )
  ```

### Command Fields

| Field | Type | Description |
| --- | --- | --- |
| `checkMetadataConsistency` | integer or string | Specifies the collection to check. `1`Sets the command to check all collections in the database for metadata inconsistencies. If run on the `admin` database, it checks all collections in all databases.`"<collection>"`Sets the collection to check for metadata inconsistencies. |
| `checkIndexes` | boolean | Sets whether the command also checks indexes in sharding metadata. For more information, see [Check Indexes.](https://www.mongodb.com/docs/manual/reference/command/checkmetadataconsistency.md#std-label-checkMetadataConsistency-indexes) |
| `cursor` | document | Configures the return cursor. |
| `cursor.batchSize` | integer | Maximum number of inconsistency results to include in each batch. |
| `dbMetadataLockMaxTimeMS` | integer | Optional. Maximum time in milliseconds that the command is allowed to wait to acquire a database lock. You can also use this field with [`maxTimeMS`](https://www.mongodb.com/docs/manual/tutorial/terminate-running-operations.md#std-label-max-time-ms). For example, if you set `dbMetadataLockMaxTimeMS` to 500 and `maxTimeMS` to 5000, the operation waits 500 milliseconds to try to acquire the database lock and waits a total of 5000 milliseconds for the entire operation to finish. |
| `performStrictChunkChecksIfBelowThreshold` | integer | **New in version 9.0** Optional. Chunk-count threshold that determines how thoroughly the command compares a shard's chunk metadata for the checked collection. If the shard owns fewer chunks for the collection than this threshold, the command performs a full comparison. The command checks every chunk's metadata across the config server, the shard, and the in-memory chunk map.; If the shard's chunk count meets or exceeds the threshold, the command instead compares only the total chunk count and the highest chunk version. The default value is `1152921504606846975` (2 60 - 1) chunks, which means that by default, the command always performs the strict check with full comparison. For more information, see [Chunk Check Threshold.](https://www.mongodb.com/docs/manual/reference/command/checkmetadataconsistency.md#std-label-checkMetadataConsistency-chunk-check-threshold) |

### Output

The `checkMetadataConsistency` command returns a cursor with a document for each inconsistency found in sharding metadata. To learn more, see [Inconsistency Types.](https://www.mongodb.com/docs/manual/reference/inconsistency-type.md#std-label-inconsistency-types)

The return document has the following fields:

| Field | Type | Description |
| --- | --- | --- |
| `cursor` | document | Cursor with the results of the inconsistency checks. |
| `cursor.id` | integer | A 64-bit integer indicated the cursor ID.  Use the `cursor.id` value with the [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) command to retrieve the next batch of inconsistencies. If the cursor returns an ID of `0`, it indicates that there are no more batches of information. |
| `cursor.ns` | string | The database and collection checked for inconsistencies. |
| `cursor.firstBatch` | array | Results of metadata consistency checks. |
| `ok` | boolean | Indicates whether the command was successful. |

## Behavior

### Batch Results

The `checkMetadataConsistency` command returns results in batches. To customize the batch size, the `batchSize` option:

```javascript
var cur = db.runCommand( {
   checkMetadataConsistency: 1,
   cursor: {
      batchSize: 10
   }
} )
```

If the `cursor.id` field is greater than 0, you can use with the [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) command to retrieve the next batch of results.

### Check Indexes

The `checkMetadataConsistency` command does not check indexes by default. To check metadata consistency and indexes, use the `checkIndexes` option:

```javascript
db.runCommand( {
   checkMetadataConsistency: 1,
   checkIndexes: true
} )
```

### Chunk Check Threshold

By default, the `checkMetadataConsistency` command performs a full comparison of every chunk's metadata across the config server, the shard, and the in-memory chunk map. On a shard that owns a large number of chunks, this comparison can increase how long the command holds its metadata lock. A large number of chunks can also increase the amount of data the command reads from the config server.

To reduce this impact, set `performStrictChunkChecksIfBelowThreshold` to a chunk count. When a shard's chunk count for the checked collection is less than this threshold, the command performs the full chunk comparison. When the count meets or exceeds the threshold, the command compares only the total chunk count and the highest chunk version instead:

```javascript
db.runCommand( {
   checkMetadataConsistency: 1,
   performStrictChunkChecksIfBelowThreshold: 10000
} )
```

## Example

Use [`runCommand()`](https://www.mongodb.com/docs/manual/reference/method/db.runcommand.md#mongodb-method-db.runCommand) to run the `checkMetadataConsistency` command:

```javascript
db.runCommand( { checkMetadataConsistency: 1 } )
```

Example Output:

```json
{
   cursor: {
      id: Long("0"),
      ns: "test.$cmd.aggregate",
      firstBatch: [
         {
            type: "MisplacedCollection",
            description: "Unsharded collection found on shard different from database primary shard",
            details: {
               namespace: "test.authors",
               shard: "shard02",
               localUUID: new UUID("1ad56770-61e2-48e9-83c6-8ecefe73cfc4")
            }
         }
      ],
   },
   ok: 1
}
```