MongoDB KB Articles

MongoDB Knowledge Base — Article Index

This local skill provides a complete index of MongoDB’s internal Knowledge Base (~2717 articles) for use in customer troubleshooting, escalation research, and code-pattern lookup.

When to use this skill

Use this skill when you need to:

• Match customer-reported symptoms to KB articles
• Find articles to share with customers (Public visibility only)
• Research known issues, error codes, or resolution procedures
• Look up MongoDB behavior for replica sets, Atlas, sharding, performance, auth, or backups
• Generate code or advice grounded in official MongoDB KB guidance
• Diagnose error codes returned by mongod, mongos, or drivers
• Troubleshoot connectivity, authentication, replication, or sharding failures
• Run diagnostic commands and interpret their output
• Investigate Atlas-specific issues (IP allowlist, VPC peering, cluster scaling)
• Analyze slow query plans and profiler output
• Prepare escalation summaries with supporting diagnostic evidence

Primary keywords

error code, troubleshoot, KB, knowledge base, support article, replica set, connectivity, atlas, performance, index, aggregation, shard, authentication, ssl, tls, timeout, oplog, writeconcern, readpreference, backup, restore, wiredtiger, replication, failover, slow query, memory, storage, monitoring, alert, upgrade, driver, schema, ldap, kerberos, x.509, currentOp, profiler, explain, serverStatus, FTDC, flowControl, balancer, chunk migration, StaleConfig, election, rollback, initial sync, DNS SRV, SCRAM, connection pool, cursor, transaction, write conflict, document validation

Context file

The full article index is maintained as the MongoDB KB context document (kb-context.md), generated from the MongoDB KB article source and synced into the mdb-context-hub skill pack as skills/contexts/mongodb-kb.md.

• Quick Reference section: top ~50 most broadly applicable articles, grouped by topic
• Category Index: all articles grouped by concept (Configuration, Security, Performance, Replication, Sharding, etc.)
• Each entry includes: article ID, title, summary, internal URL (knowledge.corp.mongodb.com), shareable URL (support.mongodb.com), products, visibility (Public/Internal), and when-to-use guidance

Usage guidance

1. Start at the Quick Reference section for common support scenarios
2. For specific topics, jump to the relevant category section
3. Always check Visibility before sharing a URL with a customer — only share Public articles
4. Use the shareableurl (support.mongodb.com) for customer-facing links
5. Use the internalurl (knowledge.corp.mongodb.com) when referencing internally

Error Code Quick Reference

The MongoDB server returns numeric error codes with every failed operation. Use this table to quickly identify the category and likely root cause, then search the KB for the specific article.

Reference: https://www.mongodb.com/docs/manual/reference/error-codes/

Authentication and Authorization Errors

SCRAM authentication troubleshooting

• SCRAM-SHA-256 disabled: Occurs when the user was created with only SCRAM-SHA-1 credentials but the server or client forces SHA-256. Fix: recreate the user or update credentials with db.updateUser().
• storedKey mismatch: The password hash stored in admin.system.users does not match. Usually caused by password rotation without updating all nodes, or restoring a backup with stale user docs.
• Mechanism negotiation: Drivers negotiate SCRAM-SHA-256 first (MongoDB 4.0+). If the server only supports SCRAM-SHA-1, set authMechanism=SCRAM-SHA-1 explicitly in the connection string.
• LDAP bind failures: When using LDAP proxy auth (PLAIN mechanism), verify the mongod can reach the LDAP server, the bind credentials are correct, and the LDAP user DN mapping is accurate. Check mongod log for LDAP connection error messages.
• x.509 certificate issues: Ensure the client certificate subject (O, OU, DC) matches the server’s tlsClusterAuthX509Attributes, the certificate is not expired, and the CA chain is complete.

Network and Connection Errors

Write Concern and Write Errors

Replication Errors

Sharding Errors

Index Errors

Transaction Errors

Cursor and Query Errors

Document and Validation Errors

General / Resource Errors

Connectivity Troubleshooting

Connection string diagnosis

mongodb+srv:// (DNS seed list)

1. Verify SRV record exists: nslookup -type=SRV _mongodb._tcp.<hostname>
2. Verify TXT record exists: nslookup -type=TXT <hostname>
3. The SRV record must resolve to one or more A/AAAA records (not CNAMEs)
4. Common failure: corporate DNS or VPN blocks SRV lookups – fall back to mongodb:// with explicit hosts

mongodb:// (standard)

1. Verify each host resolves: nslookup <host> or dig <host>
2. Test TCP connectivity: nc -zv <host> 27017 (or the configured port)
3. If connecting through a load balancer or proxy, ensure it supports the MongoDB wire protocol (not HTTP)

IPv6 vs IPv4

Node.js 17+ defaults to IPv6 DNS resolution. If the MongoDB server is IPv4-only:

• Set family=4 in the connection URI options
• Or set the Node.js flag --dns-result-order=ipv4first

Common connection failure patterns

Connection pool tuning

Authentication Issues

SCRAM (default mechanism)

Mechanism selection

• MongoDB 4.0+ negotiates SCRAM-SHA-256 first, falls back to SCRAM-SHA-1
• If the user was created before 4.0 (or with mechanisms: ["SCRAM-SHA-1"]), the driver may fail with AuthenticationFailed when it tries SHA-256
• Fix: either recreate the user to include SHA-256 credentials, or force authMechanism=SCRAM-SHA-1 in the connection string

Common SCRAM failures

Password special characters

Passwords containing @, :, /, % must be percent-encoded in the connection string:

mongodb://user:p%40ssw%25rd@host:27017/admin

LDAP (PLAIN mechanism)

• Requires Enterprise or Atlas
• The mongod process must be able to reach the LDAP server on the configured port (default 389 or 636 for LDAPS)
• Set --setParameter authenticationMechanisms=PLAIN (in addition to SCRAM if both are needed)
• Debug with mongoldap tool to test LDAP connectivity and user mapping
• Common failure: LDAP bind DN does not match the security.ldap.userToDNMapping regex

x.509 certificate authentication

• The client certificate’s subject (O, OU, DC attributes) must differ from the cluster member certificates
• The certificate must be signed by the same CA specified in --tlsCAFile
• The certificate must not be expired (openssl x509 -enddate -noout -in client.pem)
• The user must exist in the $external database with a username matching the certificate subject

Kerberos (GSSAPI)

• Requires Enterprise
• The mongod host must have a valid keytab and be registered as a service principal
• The client must have a valid TGT (kinit user@REALM)
• Clock skew > 5 minutes between KDC and mongod will cause authentication failure
• DNS must resolve both forward and reverse lookups for the mongod hostname

Replication Issues

Diagnostic commands

// Replica set status (run on any member)
rs.status()

// Replication info (oplog size and window)
rs.printReplicationInfo()

// Secondary lag details
rs.printSecondaryReplicationInfo()

// Check if flow control is engaged
db.serverStatus().flowControl.isLagged

// Check oplog entries applied per second
db.serverStatus().metrics.repl.apply.ops

// View the replica set configuration
rs.conf()

// Step down the primary (triggers election)
rs.stepDown(60)  // step down for 60 seconds

Member states

Replication lag

Diagnosis

// Check lag on each secondary
rs.printSecondaryReplicationInfo()

// Check flow control (MongoDB 4.2+)
db.serverStatus().flowControl
// If isLagged: true, the primary is throttling writes

// Check oplog window
rs.printReplicationInfo()
// log length should be > 24 hours (recommend 72h+)

Common causes and fixes

Oplog management

• Minimum recommended size: 24 hours of operations; 72 hours or more preferred
• Check current size: rs.printReplicationInfo() shows configured size and time range
• Resize without restart (4.0+): db.adminCommand({replSetResizeOplog: 1, size: <MB>})
• Oplog can grow beyond configured size to preserve the majority commit point
• Keep oplog size consistent across all data-bearing members

Elections and failover

• Elections are triggered by: primary step-down, primary unreachable (after electionTimeoutMillis, default 10s), rs.stepDown(), priority changes, member addition/removal
• A candidate needs votes from a majority of voting members (e.g., 2 of 3, 3 of 5)
• Priority 0 members cannot become primary but can vote
• Hidden members can vote but are not visible to driver read preferences
• Avoid even numbers of voting members (risk of tie); use an arbiter if needed
• Sequential reboots: never reboot multiple secondaries simultaneously in a 3-member set; the primary will step down due to loss of quorum

Rollback scenarios

• Rollback occurs when a former primary had writes that were not replicated to the new primary
• Data preserved: rollback data is written to <dbpath>/rollback/<ns>/<timestamp>.bson
• Prevent rollbacks: use w: "majority" write concern (guaranteed no rollback on committed writes)
• Large rollbacks: the 300 MB shutdown threshold applied to the legacy “rollback via refetch” path. MongoDB 5.0+ forces majority read concern and uses “recover to a timestamp,” which has no fixed rollback-size limit
• Inspect rollback files: bsondump <rollback-file>.bson

Initial sync

• Triggered when a new member joins or a member’s data is too stale
• The sync source must have an oplog covering the entire duration of the initial sync
• Monitor progress: rs.status().members[n].initialSyncStatus (4.4+)
• If initial sync fails repeatedly, increase oplog size on the sync source and ensure network stability
• For large datasets, consider restoring from a backup instead of initial sync (faster and less load on the source)

Sharding Issues

Diagnostic commands

// Sharding status overview
sh.status()

// Balancer state
sh.getBalancerState()        // enabled or disabled
sh.isBalancerRunning()       // actively migrating?

// Recent balancer activity
use config
db.changelog.find({what: /moveChunk/}).sort({time: -1}).limit(5)

// Chunk distribution for a collection
db.chunks.aggregate([
  {$match: {ns: "mydb.mycoll"}},
  {$group: {_id: "$shard", count: {$sum: 1}}}
])

// Check for jumbo chunks
db.chunks.find({jumbo: true})

// Orphaned documents
db.runCommand({cleanupOrphaned: "mydb.mycoll"})

// Flush routing metadata on mongos
db.adminCommand({flushRouterConfig: 1})

Balancer issues

Chunk migration failures

• Lock timeout: The balancer cannot acquire an exclusive lock on the collection. Stop long-running operations or schedule migrations during low-traffic windows.
• Insufficient disk space: The destination shard must have free space at least equal to the chunk size.
• Replication lag on destination: If secondaries on the destination shard lag, migration waits for _secondaryThrottle to be satisfied.
• Orphaned documents: After a failed migration, orphaned documents may remain. Run cleanupOrphaned to remove them.

StaleConfig errors

• Occur when a mongos has outdated routing metadata
• The driver automatically retries most StaleConfig errors
• Persistent StaleConfig: run db.adminCommand({flushRouterConfig: 1}) on the affected mongos
• After adding/removing shards or resharding, all mongos instances should refresh their metadata

Jumbo chunks

• A chunk is marked jumbo when it exceeds the configured chunk size (default 128 MB) and cannot be split
• Jumbo chunks cannot be migrated by the balancer, causing uneven distribution
• Diagnosis: db.getSiblingDB("config").chunks.find({jumbo: true})
• Fix: manually split the chunk with sh.splitAt() or sh.splitFind(), then clear the jumbo flag: db.getSiblingDB("config").chunks.updateOne({_id: <chunkId>}, {$unset: {jumbo: 1}})
• Root cause: low-cardinality shard key producing many documents with the same key value

Shard key issues

• Monotonically increasing keys (e.g., ObjectId, timestamp): all inserts go to the last shard, creating a hot shard. Use hashed shard key or compound key with a high-cardinality prefix.
• Low cardinality keys: few unique values lead to jumbo chunks that cannot be split. Choose a key with high cardinality.
• Missing shard key in queries: queries without the shard key in the filter perform scatter-gather across all shards. Always include the shard key prefix in frequent queries.
• Changing shard key values (4.2+): updates that modify the shard key value may move documents between shards. Requires retryWrites: true and uses a distributed transaction internally.

Performance Troubleshooting

Diagnostic workflow

1. Check current operations:     db.currentOp({secs_running: {$gt: 5}})
2. Review slow query log:        db.setProfilingLevel(1, {slowms: 100})
3. Analyze query plan:           db.coll.find({...}).explain("executionStats")
4. Check server resource usage:  db.serverStatus()
5. Review collection stats:      db.coll.stats()
6. Check index usage:            db.coll.aggregate([{$indexStats: {}}])
7. Monitor lock contention:      db.serverStatus().globalLock
8. Review WiredTiger cache:      db.serverStatus().wiredTiger.cache

Slow query diagnosis

Enable profiler

// Level 0: off; Level 1: slow ops only; Level 2: all ops
db.setProfilingLevel(1, {slowms: 100})

// Query the profiler
db.system.profile.find().sort({ts: -1}).limit(10)

// Check for COLLSCAN (full collection scan)
db.system.profile.find({planSummary: "COLLSCAN"}).sort({ts: -1})

Interpret explain output

Key fields in explain("executionStats"):

Examined-to-returned ratio: If totalDocsExamined / nReturned > 10, the query is scanning too many documents. Add a covering index or refine the query filter.

Common slow query patterns

currentOp analysis

// Find long-running operations (> 5 seconds)
db.currentOp({
  active: true,
  secs_running: {$gt: 5},
  op: {$ne: "none"}
})

// Find operations waiting for locks
db.currentOp({waitingForLock: true})

// Find operations waiting for flow control
db.aggregate([
  {$currentOp: {}},
  {$match: {waitingForFlowControl: true}}
])

// Kill a specific operation
db.killOp(<opId>)

WiredTiger cache monitoring

const wt = db.serverStatus().wiredTiger.cache;

// Cache utilization (should be < 80% of configured cache size)
print("Cache used:", Math.round(wt["bytes currently in the cache"] / 1024 / 1024), "MB");
print("Cache configured:", Math.round(wt["maximum bytes configured"] / 1024 / 1024), "MB");
print("Dirty bytes:", Math.round(wt["tracked dirty bytes in the cache"] / 1024 / 1024), "MB");
print("Pages evicted:", wt["pages evicted by application threads"]);
// If "pages evicted by application threads" is growing, the cache is under pressure

Memory and resource issues

Atlas-Specific Issues

IP access list (allowlist)

• Every client IP must be in the project’s IP Access List (Network Access in Atlas UI)
• 0.0.0.0/0 allows access from anywhere (not recommended for production)
• Dynamic IPs (home ISP, serverless functions) require either 0.0.0.0/0 or a static IP solution (NAT gateway, VPN, bastion host)
• Changes to the IP access list take effect within 1-2 minutes
• Atlas shared-tier (M0/M2/M5) does not support VPC peering; must use IP access list

VPC / network peering

• Available on M10+ dedicated clusters
• After creating a peering connection, you must also add the peered VPC CIDR to the IP Access List
• The peering connection establishes network-level routing, but Atlas still enforces IP-based access control
• For AWS: ensure the VPC route table includes a route to the Atlas CIDR
• For GCP: VPC peering is automatic with network peering; no route table changes needed
• For Azure: ensure the VNet address space does not overlap with the Atlas CIDR
• Private endpoints (AWS PrivateLink, Azure Private Link, GCP Private Service Connect) are preferred over peering for production

Atlas connection troubleshooting checklist

1. Verify cluster is deployed and status is “Active” in the Atlas UI
2. Confirm the database user exists and has the correct roles
3. Check the IP Access List includes the client’s current public IP
4. Test DNS resolution: nslookup <cluster-hostname>.mongodb.net
5. Test TCP connectivity: nc -zv <cluster-hostname>.mongodb.net 27017
6. Verify the connection string uses mongodb+srv:// with the correct cluster hostname
7. For VPC peering: confirm the peering connection status is “Active” and CIDR is in the access list
8. For private endpoints: confirm the endpoint status is “Available” in both Atlas and the cloud provider
9. Check TLS: Atlas requires TLS by default; ensure tls=true in the connection string (or ssl=true for older drivers)
10. Check driver compatibility: verify the driver version supports the MongoDB server version on the Atlas cluster

Atlas-specific operational issues

Diagnostic Commands Reference

Server and instance diagnostics

// Full server status (very large output)
db.serverStatus()

// Selective server status (recommended)
db.serverStatus({
  repl: 1,
  metrics: 1,
  wiredTiger: 1,
  connections: 1,
  opcounters: 1,
  locks: 1
})

// Build information
db.adminCommand({buildInfo: 1})

// Host system info
db.adminCommand({hostInfo: 1})

// Current connections and auth state
db.adminCommand({connectionStatus: 1, showPrivileges: true})

// Connection pool statistics (for outgoing connections)
db.adminCommand({connPoolStats: 1})

// Command-line options the server was started with
db.adminCommand({getCmdLineOpts: 1})

Database and collection diagnostics

// Database statistics
db.stats()

// Collection statistics
db.collection.stats()

// Collection storage details with index sizes
db.collection.stats({indexDetails: true})

// Total data size across all collections
db.stats().dataSize

// Index usage statistics
db.collection.aggregate([{$indexStats: {}}])

// Validate collection data and indexes
db.collection.validate({full: true})

// List all indexes on a collection
db.collection.getIndexes()

Operation monitoring

// All active operations
db.currentOp({active: true})

// Slow operations (> N seconds)
db.currentOp({active: true, secs_running: {$gt: 10}})

// Operations by namespace
db.currentOp({ns: "mydb.mycoll"})

// Operations by type
db.currentOp({op: "query"})  // query, insert, update, remove, command

// Kill a long-running operation
db.killOp(<opId>)

// Top: per-collection operation timings
db.adminCommand({top: 1})

// Recent log messages
db.adminCommand({getLog: "global"})
db.adminCommand({getLog: "startupWarnings"})

Replication diagnostics

rs.status()                           // Replica set member states and health
rs.conf()                             // Replica set configuration
rs.printReplicationInfo()             // Oplog size and time range
rs.printSecondaryReplicationInfo()    // Lag per secondary
db.serverStatus().flowControl         // Flow control metrics
db.serverStatus().metrics.repl        // Replication metrics
db.getReplicationInfo()               // Programmatic oplog info

Sharding diagnostics

sh.status()                           // Cluster overview
sh.getBalancerState()                 // Is balancer enabled?
sh.isBalancerRunning()                // Is balancer currently active?
db.adminCommand({balancerStatus: 1})  // Detailed balancer status
db.adminCommand({listShards: 1})      // All shards in the cluster

// Config database queries
use config
db.shards.find()                      // Shard definitions
db.chunks.find({ns: "db.coll"})       // Chunk distribution
db.changelog.find().sort({time: -1}).limit(10)  // Recent balancer events
db.mongos.find()                      // Connected mongos instances
db.settings.find()                    // Cluster settings (chunk size, balancer)

FTDC (Full-Time Diagnostic Data Capture)

• Enabled by default on all MongoDB deployments
• Captures serverStatus, replSetGetStatus, and other metrics every 1 second
• Stored in <dbpath>/diagnostic.data/
• Analyze with mongod --ftdc tools or third-party tools like keyhole, mdiag
• For Atlas: download FTDC data from the Atlas UI under the cluster’s “…” menu
• FTDC does not capture query shapes or slow queries – use the profiler for those

Log analysis

Log structure (MongoDB 4.4+ structured logging)

MongoDB 4.4+ uses structured JSON logging. Key fields:

• t.$date: timestamp
• s: severity (F, E, W, I, D1-D5)
• c: component (ACCESS, COMMAND, CONTROL, NETWORK, QUERY, REPL, SHARDING, STORAGE, etc.)
• id: message ID (stable across versions)
• ctx: context (connection ID, thread name)
• msg: human-readable message
• attr: structured attributes (query shape, duration, planSummary, etc.)

Key log messages to watch

Log message IDs are version-specific. Only 51803 (COMMAND slow op) is reliably stable across versions; confirm the others against the target deployment’s MongoDB version before relying on them.

Filtering logs with jq

# Find slow operations
cat mongod.log | jq 'select(.c == "COMMAND" and .attr.durationMillis > 1000)'

# Find authentication failures
cat mongod.log | jq 'select(.c == "ACCESS" and .s == "E")'

# Find replication state changes
cat mongod.log | jq 'select(.c == "REPL" and .msg | test("transition"))'

# Find network errors
cat mongod.log | jq 'select(.c == "NETWORK" and .s == "E")'

Escalation and Support Workflow

When to escalate

• Customer is experiencing data loss or corruption
• A node is in an unrecoverable state (repeated crash loop, ROLLBACK that never completes)
• Performance degradation with no identifiable root cause after profiler and explain analysis
• Cluster-wide issues affecting availability (elections every few minutes, split-brain)
• Atlas-specific issues that cannot be resolved through the UI or API (stuck scaling operations, billing anomalies)

Information to collect for escalation

1. MongoDB version: db.adminCommand({buildInfo: 1}).version
2. Topology: standalone / replica set / sharded cluster; number of members; Atlas tier
3. Server status snapshot: db.serverStatus() (full output)
4. Replica set status: rs.status() (if applicable)
5. Sharding status: sh.status() (if applicable)
6. FTDC data: from <dbpath>/diagnostic.data/ or Atlas download
7. Log excerpts: relevant log lines with timestamps (use structured JSON format)
8. Profiler output: db.system.profile.find().sort({ts: -1}).limit(20) for slow query issues
9. Explain plans: db.coll.find({...}).explain("executionStats") for query performance issues
10. Timeline: when the issue started, any recent changes (deployments, config changes, scaling)
11. Impact: number of users affected, error rates, latency percentiles
12. Reproduction steps: if the issue is reproducible

Support escalation templates

Connectivity issue template

Subject: Connectivity failure — [cluster-name]

Environment: Atlas M30 / Self-managed 7.0.x
Topology: 3-node replica set, region: us-east-1
Driver: Node.js v6.x / Java Sync v5.x / Python v4.x

Symptoms:
- Error: [exact error message]
- First observed: [timestamp]
- Frequency: [constant / intermittent / periodic]

Steps taken:
1. Verified IP access list
2. Tested DNS resolution: [results]
3. Tested TCP connectivity: [results]
4. Checked server logs: [relevant log excerpts]

Attachments: FTDC data, server logs, connection string (redacted)

Performance issue template

Subject: Slow query performance — [collection-name]

Environment: Atlas M50 / Self-managed 8.0.x
Collection size: [doc count, data size, index count]
Query pattern: [the query or aggregation pipeline]

Symptoms:
- Average latency: [before] -> [now]
- Profiler output: [attached or inline]
- Explain plan: [attached or inline]

Steps taken:
1. Ran explain("executionStats"): [key findings]
2. Checked index usage: [$indexStats results]
3. Checked server resources: [cache utilization, connections, tickets]

Attachments: explain output, profiler entries, serverStatus snapshot

References

• MongoDB Error Codes: https://www.mongodb.com/docs/manual/reference/error-codes/
• Connection Troubleshooting (Node.js Driver): https://www.mongodb.com/docs/drivers/node/current/connect/connection-troubleshooting/
• Connection Troubleshooting (Java Driver): https://www.mongodb.com/docs/drivers/java/sync/current/connection/connection-troubleshooting/
• Troubleshoot Replica Sets: https://www.mongodb.com/docs/manual/tutorial/troubleshoot-replica-sets/
• Troubleshoot Sharded Clusters: https://www.mongodb.com/docs/manual/tutorial/troubleshoot-sharded-clusters/
• Monitor Slow Queries: https://www.mongodb.com/docs/manual/tutorial/monitor-slow-queries/
• Database Profiler: https://www.mongodb.com/docs/manual/tutorial/find-slow-queries-with-database-profiler/
• Explain Slow Queries: https://www.mongodb.com/docs/manual/tutorial/explain-slow-queries/
• Diagnostic Commands: https://www.mongodb.com/docs/manual/reference/command/nav-diagnostic/
• serverStatus Reference: https://www.mongodb.com/docs/manual/reference/command/serverstatus/
• replSetGetStatus Reference: https://www.mongodb.com/docs/manual/reference/command/replsetgetstatus/
• Atlas FAQ Networking: https://www.mongodb.com/docs/atlas/reference/faq/networking/
• Atlas Connection Troubleshooting: https://www.geeksforgeeks.org/mongodb/troubleshooting-mongodb-atlas-connection-errors/
• Monitoring Self-Managed Deployments: https://www.mongodb.com/docs/manual/administration/monitoring/
• Exit Codes and Statuses: https://www.mongodb.com/docs/manual/reference/exit-codes/
• Query Performance: https://www.mongodb.com/docs/manual/administration/query/
• MongoDB Replication Internals: https://github.com/mongodb/mongo/blob/master/src/mongo/db/repl/README.md