Introduction

MongoDB balancer not moving chunks when chunk migration blocked or balancer disabled. This guide provides step-by-step diagnosis and resolution.

Symptoms

Typical error output:

bash
Error: Chunk migration failed
Balancer stopped: waiting for chunk migration to complete
Chunk migration aborted due to: recipient shard not ready

Common Causes

  1. 1.Balancer disabled or in maintenance window
  2. 2.Chunk migration blocked by concurrent operations
  3. 3.Recipient shard disk or memory insufficient
  4. 4.Config server replica set issue

Step-by-Step Fix

Step 1: Check Current State

javascript
sh.status()
db.adminCommand({balancerStatus: 1})
db.chunks.find().count()

Step 2: Identify Root Cause

javascript
rs.status()
db.serverStatus()
db.currentOp()

Step 3: Apply Primary Fix

```javascript // Enable balancer sh.enableBalancing("myDatabase.myCollection") sh.startBalancer()

// Check chunk distribution db.adminCommand({moveChunk: "myDatabase.myCollection", find: {shardKey: 1}, to: "shard02"}) ```

Step 4: Apply Alternative Fix

```javascript // Alternative fix: Check configuration rs.conf() db.adminCommand({getCmdLineOpts: 1})

// Update settings db.adminCommand({setParameter: 1, parameter: value})

// Verify the fix db.serverStatus().metrics ```

Step 5: Verify the Fix

javascript
sh.status()
db.adminCommand({balancerStatus: 1})
// Chunks should be evenly distributed

Common Pitfalls

  • Not checking replica set status before operations
  • Using unbounded queries on large collections
  • Forgetting to create indexes for query patterns
  • Ignoring memory limits in aggregation pipelines

Best Practices

  • Monitor replication lag and oplog size
  • Create indexes to support common queries
  • Use covered queries to reduce document scans
  • Implement retry logic for transient errors
  • MongoDB Replica Set Election
  • MongoDB Sharding Chunk Migration
  • MongoDB Aggregation Pipeline Error
  • MongoDB Connection Failed