Troubleshooting DocumentDB: Common Issues and Solutions

Introduction to Amazon DocumentDB Troubleshooting

Amazon DocumentDB is a fully managed, MongoDB-compatible database service designed for fast, scalable, and highly available document database workloads. While AWS handles much of the operational overhead, developers and database administrators still encounter issues related to performance, connectivity, replication, and query behavior. This tutorial walks through the most common DocumentDB problems and provides actionable solutions with practical examples.

Understanding how to troubleshoot DocumentDB effectively matters because misdiagnosed issues can lead to prolonged downtime, degraded application performance, and unexpected cost overruns. Because DocumentDB emulates the MongoDB API but runs on a different underlying storage engine (Aurora-style distributed storage), some MongoDB-specific assumptions do not apply. Recognizing these differences is the first step toward effective debugging.

Common Connectivity Issues

Connection Refused and Timeout Errors

The most frequent DocumentDB issue developers face is the inability to connect. This typically stems from security group misconfiguration, missing IAM authentication, or incorrect TLS handling. DocumentDB clusters enforce TLS by default, and connections that omit the proper certificate bundle will fail silently or with cryptic timeout errors.

Here is a common Node.js connection example that includes the required TLS certificate:

const { MongoClient } = require('mongodb');

const uri = 'mongodb://<user>:<password>@<cluster-endpoint>:27017/?tls=true&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false';
const client = new MongoClient(uri, {
  tlsCAFile: './rds-combined-ca-bundle.pem',
  serverSelectionTimeoutMS: 5000
});

async function connect() {
  try {
    await client.connect();
    console.log('Connected to DocumentDB');
    const db = client.db('mydb');
    const collections = await db.listCollections().toArray();
    console.log(collections);
  } catch (err) {
    console.error('Connection failed:', err.message);
  } finally {
    await client.close();
  }
}

connect();

If you receive a connection timeout, verify the following checklist:

The EC2 instance or Lambda function is in the same VPC or has VPC peering configured correctly.
The security group attached to the DocumentDB cluster allows inbound traffic on port 27017 from the client's security group.
The IAM role or database credentials are valid and not expired.
The CA bundle file is the latest version downloaded from AWS.
The cluster endpoint, not the instance endpoint, is used when connecting through a replica set.

Authentication Errors with IAM

When using IAM database authentication, developers often forget that the MongoDB driver must generate a temporary authentication token. Standard username and password connections will not work if IAM auth is enforced. Below is a Python example using boto3 to generate the token and pymongo to connect:

import boto3
import pymongo
from pymongo.auth_oidc import OIDCCallback

rds_client = boto3.client('rds')

cluster_endpoint = 'my-cluster.cluster-xxxxxx.us-east-1.docdb.amazonaws.com'
port = 27017
region = 'us-east-1'
username = 'iam-user'

# Generate the IAM auth token
token = rds_client.generate_db_auth_token(
    DBHostname=cluster_endpoint,
    Port=port,
    DBUsername=username,
    Region=region
)

client = pymongo.MongoClient(
    host=cluster_endpoint,
    port=port,
    username=username,
    password=token,
    tls=True,
    tlsCAFile='rds-combined-ca-bundle.pem',
    authSource='$external',
    authMechanism='MONGODB-AWS',
    retryWrites=False
)

db = client['mydb']
print(db.list_collection_names())

Performance and Query Optimization

Slow Queries and Missing Indexes

Slow queries are the second most common DocumentDB complaint. Because DocumentDB uses a distributed storage architecture, full collection scans are particularly expensive. The first diagnostic step is always to run explain() on the query to inspect the execution plan.

// Connect via mongosh or your driver
const db = db.getSiblingDB('mydb');

const explanation = db.orders.find({
  customerId: 'cust-12345',
  status: 'shipped'
}).explain('executionStats');

printjson(explanation);

If the output shows COLLSCAN instead of IXSCAN, the query is performing a full collection scan. Create a compound index to cover the query pattern:

db.orders.createIndex(
  { customerId: 1, status: 1, createdAt: -1 },
  { background: true }
);

Always create indexes with background: true in production to avoid blocking operations. Monitor index creation progress using the following command:

db.currentOp({
  'command.createIndexes': { $exists: true }
});

High CPU Utilization

When CloudWatch reports sustained high CPU utilization on your DocumentDB instances, the root cause is usually one of the following: inefficient queries, insufficient indexing, undersized instance types, or excessive concurrent connections. Use the $currentOp aggregation to identify long-running operations:

db.aggregate([
  { $currentOp: { allUsers: true, idleConnections: false } },
  { $match: { 'microsecs_running': { $gt: 1000000 } } },
  { $sort: { 'microsecs_running': -1 } },
  { $limit: 10 }
]);

For operations that cannot be optimized further, consider vertically scaling the instance type or adding read replicas to distribute read traffic. Remember that DocumentDB read replicas can be promoted to handle read-heavy workloads using the readPreference connection parameter.

Replication and Failover Problems

Replica Lag Alerts

DocumentDB maintains replicas at the storage layer, which generally provides low replication lag. However, heavy write workloads on the primary instance can cause replica lag to spike, leading to stale reads on secondary instances. Monitor replica lag through CloudWatch metrics, specifically DBInstanceReplicaLag.

If replica lag exceeds acceptable thresholds, investigate these causes:

Large bulk write operations overwhelming the storage layer.
Insufficient IOPS provisioned on the cluster volume.
Network bottlenecks between the primary and replica instances.
Long-running transactions holding locks that delay replication.

To identify long-running transactions, run:

db.aggregate([
  { $currentOp: { allUsers: true, idleCursors: false } },
  { $match: { 'transaction': { $exists: true } } },
  { $project: { 'opid': 1, 'secs_running': 1, 'command': 1 } },
  { $sort: { 'secs_running': -1 } }
]);

Kill problematic operations using the opid:

db.killOp(opid);

Failover Not Triggering

DocumentDB automatically fails over to a read replica when the primary instance becomes unhealthy. If failover does not occur, verify that at least one read replica exists in a different Availability Zone. Multi-AZ deployments are essential for high availability. Check the cluster configuration:

aws docdb describe-db-clusters \
  --db-cluster-identifier my-cluster \
  --region us-east-1

Ensure the MultiAZ field is set to true and that the DBClusterMembers list includes instances across multiple AZs. If not, add a replica:

aws docdb create-db-instance \
  --db-instance-identifier my-replica-2 \
  --db-instance-class db.r5.large \
  --engine docdb \
  --db-cluster-identifier my-cluster \
  --availability-zone us-east-1c

Storage and Capacity Issues

Storage AutoScaling Not Working

DocumentDB automatically grows storage in 10 GB increments as needed, but if you have disabled auto-scaling or hit account-level limits, writes will fail with storage full errors. Check current storage utilization:

aws cloudwatch get-metric-statistics \
  --namespace AWS/DocDB \
  --metric-name VolumeBytesUsed \
  --dimensions Name=DBClusterIdentifier,Value=my-cluster \
  --start-time 2024-01-01T00:00:00Z \
  --end-time 2024-01-02T00:00:00Z \
  --period 3600 \
  --statistics Average

If storage is near capacity, either enable storage auto-scaling or manually increase the allocated storage. Note that DocumentDB storage cannot be decreased once allocated, so plan capacity carefully.

Connection Pool Exhaustion

Each DocumentDB instance has a maximum connection limit based on its instance class. When applications open too many connections without closing them, new connections are rejected. Monitor the DatabaseConnections CloudWatch metric and configure connection pooling appropriately in your application.

For Node.js applications using mongoose, configure pool size sensibly:

const mongoose = require('mongoose');

mongoose.connect(uri, {
  tlsCAFile: './rds-combined-ca-bundle.pem',
  maxPoolSize: 50,
  minPoolSize: 5,
  serverSelectionTimeoutMS: 5000,
  socketTimeoutMS: 45000
});

Best Practices for DocumentDB Operations

Use the cluster endpoint for writes and reader endpoints for read-heavy workloads to distribute traffic across replicas.
Enable Performance Insights on all DocumentDB instances to get granular query-level performance data.
Implement exponential backoff in application retry logic to handle transient connection failures gracefully.
Regularly review slow query logs exported to CloudWatch Logs to catch performance regressions early.
Test failover procedures in staging environments using the aws docdb failover-db-cluster command to validate application resilience.
Avoid large transactions that span many documents, as DocumentDB handles small, targeted operations more efficiently.
Use change streams cautiously — they consume additional resources and can impact performance under heavy write loads.
Tag resources properly to track costs and identify underutilized clusters that can be downsized or terminated.

Conclusion

Troubleshooting Amazon DocumentDB requires a combination of MongoDB query knowledge and AWS-specific operational awareness. By understanding the common failure modes — connectivity, performance, replication, and storage — and applying the diagnostic techniques and solutions covered in this tutorial, you can resolve most DocumentDB issues quickly and prevent them from recurring. The key is to combine proactive monitoring through CloudWatch with reactive debugging tools like $currentOp and explain(), while always keeping your connection configuration, indexing strategy, and instance sizing aligned with your actual workload demands.