# How to Verify the Overall Cluster Health and Status Using the sh.status() Command

> Learn to check MongoDB cluster health and status with sh.status() in the MongoDB shell. Quickly verify your Docker-based cluster topology including shards replica sets and mongos routers.

- Repository: [Jin/mongodb-cluster-docker-compose](https://github.com/minhhungit/mongodb-cluster-docker-compose)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Use the `sh.status()` command in the MongoDB shell to query the config server metadata and display the complete topology of shards, replica sets, and mongos routers in your Docker-based cluster.**

The `minhhungit/mongodb-cluster-docker-compose` repository provides a production-ready sharded MongoDB cluster orchestrated via Docker Compose. To verify the overall cluster health and status using the `sh.status()` command, you connect to any `mongos` router instance and invoke the helper, which returns the authoritative view of the cluster topology stored in the config servers.

## Why Use sh.status() for Cluster Verification

The `sh.status()` helper is the canonical method for inspecting a sharded cluster because it aggregates metadata from the config server replica set into a single, readable report. Unlike checking individual shard nodes with `rs.status()`, this command validates the entire ecosystem—including the balancer state, chunk distribution, and router connectivity.

### What the Command Queries

When executed, `sh.status()` connects to the config server replica set defined in the `mongos` startup parameters. In the [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) file, the router service (`router-01`) is initialized with the `--configdb` flag pointing to the config server replica set (`cfgrs`). The command reads from the `config.shards`, `config.mongos`, and `config.settings` collections to build its report.

### Information Returned

The output contains four critical health indicators:

* **Sharding version** – The version of the cluster metadata protocol.
* **Shards** – A list of every shard replica set, including member hostnames, ports, and state codes.
* **Active mongoses** – The number of router processes currently registered with the config servers.
* **Balancer** – Whether the balancer is enabled and its current operational state.

## Running sh.status() in the Docker Environment

The repository provides multiple pathways to execute the command depending on your authentication setup and whether you prefer interactive shells or one-liners.

### Inside the Router Container

The most direct method uses `docker exec` to pipe the command into the `mongosh` client running inside the `router-01` container defined in the root [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml).

```bash
docker exec -it router-01 bash -c \
  "echo 'sh.status()' | mongosh --port 27017"

```

This approach requires no local MongoDB installation and works immediately after the containers start.

### Using Docker Compose Exec

For better readability and consistency with the Compose workflow shown in the [`readme.md`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/readme.md) (lines 49-55), use the `docker-compose exec` shortcut to open an interactive `mongosh` session.

```bash
docker-compose exec router01 mongosh --port 27017

```

Once inside the shell, run:

```javascript
sh.status()

```

This method is preferred when you need to run multiple diagnostic commands sequentially.

### With Keyfile Authentication Enabled

When deploying the cluster with authentication enabled (as documented in [`with-keyfile-auth/readme.md`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/readme.md), lines 89-100), you must provide credentials to query the config servers. The command requires the `-u` and `-p` flags along with `--authenticationDatabase`.

```bash
docker exec -it router-01 bash -c \
  "echo 'sh.status()' | mongosh --port 27017 \
   -u 'your_admin' -p 'your_password' \
   --authenticationDatabase admin"

```

Failure to authenticate will result in an authorization error because the config server collections are protected.

### From the Host Machine

If you have `mongosh` installed locally, you can connect through the exposed port mappings defined in [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) (typically `27117` or `27118` mapped to container port `27017`).

```bash
mongosh --host 127.0.0.1 --port 27117 \
        -u "your_admin" --authenticationDatabase admin

```

Then execute `sh.status()` inside the shell. This avoids container context switching but requires proper port mapping and local client installation.

## Interpreting the Output

Understanding the `sh.status()` report is essential for diagnosing cluster health. The output structure reflects the internal state stored in the config server replica set.

### Sharding Version and Metadata

The first block displays the cluster metadata protocol version:

```javascript
sharding version: {
  _id: 1,
  minCompatibleVersion: 5,
  currentVersion: 6,
  clusterId: ObjectId("...")
}

```

A version mismatch between config servers and routers indicates an incomplete upgrade or configuration drift. The `clusterId` should remain consistent across all `mongos` instances.

### Shard Topology and Member States

The `shards` array lists every shard replica set. Healthy members show `"state" : 1` (PRIMARY) or `"state" : 2` (SECONDARY). As noted in the repository documentation, if all members of a shard display `"state" : 2` and no primary is elected, the cluster cannot route writes to that shard.

```javascript
shards:
  {  "_id": "shard01",  "host": "shard01/shard01-a:27018,shard01-b:27018,shard01-c:27018",  "state": 1 }
  {  "_id": "shard02",  "host": "shard02/shard02-a:27019,shard02-b:27019,shard02-c:27019",  "state": 1 }

```

The `host` field confirms the replica set name and member addresses match the Docker service names defined in [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml).

### Balancer and Mongos Status

The final sections report operational health:

* **active mongoses**: Counts the number of `mongos` router processes currently heartbeating to the config servers. A count of zero indicates all routers are down or network partitioned.
* **balancer**: Shows whether the chunk balancer is enabled and currently running. For a healthy idle cluster, expect `currently enabled: yes` and `currently running: no`.

```javascript
active mongoses:
  "4.4.x": 2

balancer:
  Currently enabled: yes
  Currently running: no

```

If the balancer reports `Currently running: yes` for extended periods without data ingestion, investigate for orphaned chunks or jumbo chunks blocking migration.

## Key Files in the Repository

The following files define the cluster topology and verification workflow:

| File | Purpose | Location |
|------|---------|----------|
| [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) | Defines the `router-01` service, config server replica set, and shard nodes that `sh.status()` queries. | [Root directory](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/docker-compose.yml) |
| [`readme.md`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/readme.md) | Contains the "Verify the status of the sharded cluster" section with exact `sh.status()` commands. | [Root readme](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/readme.md#verify-the-status-of-the-sharded-cluster) |
| [`with-keyfile-auth/readme.md`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/readme.md) | Documents authentication-required verification steps for hardened deployments. | [with-keyfile-auth directory](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/with-keyfile-auth/readme.md#verify-the-status-of-the-sharded-cluster) |
| [`scripts/entrypoint-router.sh`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/scripts/entrypoint-router.sh) | Initializes the `mongos` router process, ensuring it can respond to `sh.status()` queries. | [scripts directory](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/master/scripts/entrypoint-route.sh) |

## Summary

To verify the overall cluster health and status using the `sh.status()` command in the `minhhungit/mongodb-cluster-docker-compose` repository:

* Execute `sh.status()` from any `mongos` router container to query the config server metadata.
* Inspect the `shards` array for `"state" : 1` (PRIMARY) on all shard replica sets.
* Confirm `active mongoses` shows the expected router count and the `balancer` reports `enabled: yes`.
* Use authenticated commands (`-u` and `-p`) when running the **with-keyfile-auth** variant documented in [`with-keyfile-auth/readme.md`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/readme.md).

## Frequently Asked Questions

### What does it mean if a shard shows state 2 instead of state 1?

A `state` value of `2` indicates the member is a SECONDARY node. If **all** members of a shard replica set show `state: 2` and no primary is listed, the shard has no elected primary. According to the repository documentation, this prevents the cluster from routing writes to that shard and indicates an unhealthy replica set requiring immediate attention.

### Can I run sh.status() from any container, or only the router?

You should run `sh.status()` from a **mongos router** container (such as `router-01` defined in [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml)). While you can technically connect to a config server directly and query the `config` database, the `sh.status()` helper is designed to run against `mongos` routers. Running it from shard containers or config servers may return errors or incomplete views because those nodes do not maintain the full cluster routing table.

### Why does sh.status() require authentication in some deployments but not others?

Authentication requirements depend on whether you deployed the cluster using the standard [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml) or the **with-keyfile-auth** variant. The base configuration in the root directory starts the cluster without authentication for local development. However, the [`with-keyfile-auth/readme.md`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/with-keyfile-auth/readme.md) documents a hardened setup where `--auth` and `--keyFile` parameters are enabled. In that environment, the config server collections are protected, so `sh.status()` requires valid credentials (`-u`, `-p`, `--authenticationDatabase admin`) to read the metadata.

### How do I fix a cluster where sh.status() shows missing shards?

If `sh.status()` lists fewer shards than defined in your [`docker-compose.yml`](https://github.com/minhhungit/mongodb-cluster-docker-compose/blob/main/docker-compose.yml), or shows `"stateStr": "UNKNOWN"` for members, first verify that all shard containers are running with `docker ps`. Next, check individual shard replica set health by connecting to a shard node and running `rs.status()`. If a shard is running but not visible to `sh.status()`, you may need to re-add it using `sh.addShard()` from the `mongos` router, ensuring you use the replica set connection string format (`shard01/shard01-a:27018`) as specified in the repository's initialization scripts.