MongoDB KB Articles
Parent: MongoDB Expert Knowledge · researched 2026-05-25· 0 sources · 5 concepts · skill mongodb-kb
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.
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. [source]
When to use this skill
- Use this skill when you need to: [source]
- Match customer-reported symptoms to KB articles [source]
- Find articles to share with customers (Public visibility only) [source]
- Research known issues, error codes, or resolution procedures [source]
- Look up MongoDB behavior for replica sets, Atlas, sharding, performance, auth, or backups [source]
- Generate code or advice grounded in official MongoDB KB guidance [source]
- Diagnose error codes returned by mongod, mongos, or drivers [source]
- Troubleshoot connectivity, authentication, replication, or sharding failures [source]
- Run diagnostic commands and interpret their output [source]
- Investigate Atlas-specific issues (IP allowlist, VPC peering, cluster scaling) [source]
- Analyze slow query plans and profiler output [source]
- Prepare escalation summaries with supporting diagnostic evidence [source]
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 [source]
Context file
- The full article index is maintained as the MongoDB KB context document (kb-context.md), generated [source]
- from the MongoDB KB article source and synced into the mdb-context-hub skill pack as [source]
- skills/contexts/mongodb-kb.md. [source]
- Quick Reference section: top ~50 most broadly applicable articles, grouped by topic [source]
- Category Index: all articles grouped by concept (Configuration, Security, Performance, Replication, Sharding, etc.) [source]
- 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 [source]
Usage guidance
- Start at the Quick Reference section for common support scenarios [source]
- For specific topics, jump to the relevant category section [source]
- Always check Visibility before sharing a URL with a customer - only share Public articles [source]
- Use the shareableurl (support.mongodb.com) for customer-facing links [source]
- Use the internalurl (knowledge.corp.mongodb.com) when referencing internally [source]
Error Code Quick Reference
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(). [source]
- 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. [source]
- 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. [source]
- 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. [source]
- 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. [source]
`mongodb+srv://` (DNS seed list)
- Verify SRV record exists: nslookup -type=SRV _mongodb._tcp.<hostname> [source]
- Verify TXT record exists: nslookup -type=TXT <hostname> [source]
- The SRV record must resolve to one or more A/AAAA records (not CNAMEs) [source]
- Common failure: corporate DNS or VPN blocks SRV lookups -- fall back to mongodb:// with explicit hosts [source]
`mongodb://` (standard)
IPv6 vs IPv4
Mechanism selection
- MongoDB 4.0+ negotiates SCRAM-SHA-256 first, falls back to SCRAM-SHA-1 [source]
- 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 [source]
- Fix: either recreate the user to include SHA-256 credentials, or force authMechanism=SCRAM-SHA-1 in the connection string [source]
Password special characters
- Passwords containing @, :, /, % must be percent-encoded in the connection string: [source]
LDAP (PLAIN mechanism)
- Requires Enterprise or Atlas [source]
- The mongod process must be able to reach the LDAP server on the configured port (default 389 or 636 for LDAPS) [source]
- Set --setParameter authenticationMechanisms=PLAIN (in addition to SCRAM if both are needed) [source]
- Debug with mongoldap tool to test LDAP connectivity and user mapping [source]
- Common failure: LDAP bind DN does not match the security.ldap.userToDNMapping regex [source]
x.509 certificate authentication
- The client certificate's subject (O, OU, DC attributes) must differ from the cluster member certificates [source]
- The certificate must be signed by the same CA specified in --tlsCAFile [source]
- The certificate must not be expired (openssl x509 -enddate -noout -in client.pem) [source]
- The user must exist in the $external database with a username matching the certificate subject [source]
Kerberos (GSSAPI)
- Requires Enterprise [source]
- The mongod host must have a valid keytab and be registered as a service principal [source]
- The client must have a valid TGT (kinit user@REALM) [source]
- Clock skew > 5 minutes between KDC and mongod will cause authentication failure [source]
- DNS must resolve both forward and reverse lookups for the mongod hostname [source]
Oplog management
- Minimum recommended size: 24 hours of operations; 72 hours or more preferred [source]
- Check current size: rs.printReplicationInfo() shows configured size and time range [source]
- Resize without restart (4.0+): db.adminCommand({replSetResizeOplog: 1, size: <MB>}) [source]
- Oplog can grow beyond configured size to preserve the majority commit point [source]
- Keep oplog size consistent across all data-bearing members [source]
Elections and failover
- Elections are triggered by: primary step-down, primary unreachable (after electionTimeoutMillis, default 10s), rs.stepDown(), priority changes, member addition/removal [source]
- A candidate needs votes from a majority of voting members (e.g., 2 of 3, 3 of 5) [source]
- Priority 0 members cannot become primary but can vote [source]
- Hidden members can vote but are not visible to driver read preferences [source]
- Avoid even numbers of voting members (risk of tie); use an arbiter if needed [source]
- Sequential reboots: never reboot multiple secondaries simultaneously in a 3-member set; the primary will step down due to loss of quorum [source]
Rollback scenarios
- Rollback occurs when a former primary had writes that were not replicated to the new primary [source]
- Data preserved: rollback data is written to <dbpath>/rollback/<ns>/<timestamp>.bson [source]
- Prevent rollbacks: use w: "majority" write concern (guaranteed no rollback on committed writes) [source]
- 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 [source]
- Inspect rollback files: bsondump <rollback-file>.bson [source]
Initial sync
- Triggered when a new member joins or a member's data is too stale [source]
- The sync source must have an oplog covering the entire duration of the initial sync [source]
- Monitor progress: rs.status().members[n].initialSyncStatus (4.4+) [source]
- If initial sync fails repeatedly, increase oplog size on the sync source and ensure network stability [source]
- For large datasets, consider restoring from a backup instead of initial sync (faster and less load on the source) [source]
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. [source]
- Insufficient disk space: The destination shard must have free space at least equal to the chunk size. [source]
- Replication lag on destination: If secondaries on the destination shard lag, migration waits for _secondaryThrottle to be satisfied. [source]
- Orphaned documents: After a failed migration, orphaned documents may remain. Run cleanupOrphaned to remove them. [source]
StaleConfig errors
- Occur when a mongos has outdated routing metadata [source]
- The driver automatically retries most StaleConfig errors [source]
- Persistent StaleConfig: run db.adminCommand({flushRouterConfig: 1}) on the affected mongos [source]
- After adding/removing shards or resharding, all mongos instances should refresh their metadata [source]
Jumbo chunks
- A chunk is marked jumbo when it exceeds the configured chunk size (default 128 MB) and cannot be split [source]
- Jumbo chunks cannot be migrated by the balancer, causing uneven distribution [source]
- Diagnosis: db.getSiblingDB("config").chunks.find({jumbo: true}) [source]
- 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}}) [source]
- Root cause: low-cardinality shard key producing many documents with the same key value [source]
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. [source]
- Low cardinality keys: few unique values lead to jumbo chunks that cannot be split. Choose a key with high cardinality. [source]
- 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. [source]
- 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. [source]
Interpret explain output
IP access list (allowlist)
- Every client IP must be in the project's IP Access List (Network Access in Atlas UI) [source]
- 0.0.0.0/0 allows access from anywhere (not recommended for production) [source]
- Dynamic IPs (home ISP, serverless functions) require either 0.0.0.0/0 or a static IP solution (NAT gateway, VPN, bastion host) [source]
- Changes to the IP access list take effect within 1-2 minutes [source]
- Atlas shared-tier (M0/M2/M5) does not support VPC peering; must use IP access list [source]
VPC / network peering
- Available on M10+ dedicated clusters [source]
- After creating a peering connection, you must also add the peered VPC CIDR to the IP Access List [source]
- The peering connection establishes network-level routing, but Atlas still enforces IP-based access control [source]
- For AWS: ensure the VPC route table includes a route to the Atlas CIDR [source]
- For GCP: VPC peering is automatic with network peering; no route table changes needed [source]
- For Azure: ensure the VNet address space does not overlap with the Atlas CIDR [source]
- Private endpoints (AWS PrivateLink, Azure Private Link, GCP Private Service Connect) are preferred over peering for production [source]
Atlas connection troubleshooting checklist
- Verify cluster is deployed and status is "Active" in the Atlas UI [source]
- Confirm the database user exists and has the correct roles [source]
- Check the IP Access List includes the client's current public IP [source]
- Test DNS resolution: nslookup <cluster-hostname>.mongodb.net [source]
- Test TCP connectivity: nc -zv <cluster-hostname>.mongodb.net 27017 [source]
- Verify the connection string uses mongodb+srv:// with the correct cluster hostname [source]
- For VPC peering: confirm the peering connection status is "Active" and CIDR is in the access list [source]
- For private endpoints: confirm the endpoint status is "Available" in both Atlas and the cloud provider [source]
- Check TLS: Atlas requires TLS by default; ensure tls=true in the connection string (or ssl=true for older drivers) [source]
- Check driver compatibility: verify the driver version supports the MongoDB server version on the Atlas cluster [source]
FTDC (Full-Time Diagnostic Data Capture)
- Enabled by default on all MongoDB deployments [source]
- Captures serverStatus, replSetGetStatus, and other metrics every 1 second [source]
- Stored in <dbpath>/diagnostic.data/ [source]
- Analyze with mongod --ftdc tools or third-party tools like keyhole, mdiag [source]
- For Atlas: download FTDC data from the Atlas UI under the cluster's "..." menu [source]
- FTDC does not capture query shapes or slow queries -- use the profiler for those [source]
Log structure (MongoDB 4.4+ structured logging)
- MongoDB 4.4+ uses structured JSON logging. Key fields: [source]
- t.$date: timestamp [source]
- s: severity (F, E, W, I, D1-D5) [source]
- c: component (ACCESS, COMMAND, CONTROL, NETWORK, QUERY, REPL, SHARDING, STORAGE, etc.) [source]
- id: message ID (stable across versions) [source]
- ctx: context (connection ID, thread name) [source]
- msg: human-readable message [source]
- attr: structured attributes (query shape, duration, planSummary, etc.) [source]
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. [source]
When to escalate
- Customer is experiencing data loss or corruption [source]
- A node is in an unrecoverable state (repeated crash loop, ROLLBACK that never completes) [source]
- Performance degradation with no identifiable root cause after profiler and explain analysis [source]
- Cluster-wide issues affecting availability (elections every few minutes, split-brain) [source]
- Atlas-specific issues that cannot be resolved through the UI or API (stuck scaling operations, billing anomalies) [source]
Information to collect for escalation
- MongoDB version: db.adminCommand({buildInfo: 1}).version [source]
- Topology: standalone / replica set / sharded cluster; number of members; Atlas tier [source]
- Server status snapshot: db.serverStatus() (full output) [source]
- Replica set status: rs.status() (if applicable) [source]
- Sharding status: sh.status() (if applicable) [source]
- FTDC data: from <dbpath>/diagnostic.data/ or Atlas download [source]
- Log excerpts: relevant log lines with timestamps (use structured JSON format) [source]
- Profiler output: db.system.profile.find().sort({ts: -1}).limit(20) for slow query issues [source]
- Explain plans: db.coll.find({...}).explain("executionStats") for query performance issues [source]
- Timeline: when the issue started, any recent changes (deployments, config changes, scaling) [source]
- Impact: number of users affected, error rates, latency percentiles [source]
- Reproduction steps: if the issue is reproducible [source]
References
- MongoDB Error Codes: https://www.mongodb.com/docs/manual/reference/error-codes/ [source]
- Connection Troubleshooting (Node.js Driver): https://www.mongodb.com/docs/drivers/node/current/connect/connection-troubleshooting/ [source]
- Connection Troubleshooting (Java Driver): https://www.mongodb.com/docs/drivers/java/sync/current/connection/connection-troubleshooting/ [source]
- Troubleshoot Replica Sets: https://www.mongodb.com/docs/manual/tutorial/troubleshoot-replica-sets/ [source]
- Troubleshoot Sharded Clusters: https://www.mongodb.com/docs/manual/tutorial/troubleshoot-sharded-clusters/ [source]
- Monitor Slow Queries: https://www.mongodb.com/docs/manual/tutorial/monitor-slow-queries/ [source]
- Database Profiler: https://www.mongodb.com/docs/manual/tutorial/find-slow-queries-with-database-profiler/ [source]
- Explain Slow Queries: https://www.mongodb.com/docs/manual/tutorial/explain-slow-queries/ [source]
- Diagnostic Commands: https://www.mongodb.com/docs/manual/reference/command/nav-diagnostic/ [source]
- serverStatus Reference: https://www.mongodb.com/docs/manual/reference/command/serverstatus/ [source]
- replSetGetStatus Reference: https://www.mongodb.com/docs/manual/reference/command/replsetgetstatus/ [source]
- Atlas FAQ Networking: https://www.mongodb.com/docs/atlas/reference/faq/networking/ [source]
- Atlas Connection Troubleshooting: https://www.geeksforgeeks.org/mongodb/troubleshooting-mongodb-atlas-connection-errors/ [source]
- Monitoring Self-Managed Deployments: https://www.mongodb.com/docs/manual/administration/monitoring/ [source]
- Exit Codes and Statuses: https://www.mongodb.com/docs/manual/reference/exit-codes/ [source]
- Query Performance: https://www.mongodb.com/docs/manual/administration/query/ [source]
- MongoDB Replication Internals: https://github.com/mongodb/mongo/blob/master/src/mongo/db/repl/README.md [source]
Children
- Error Code Lookup (frontier)
- Connectivity Troubleshooting (frontier)
- Replica Set Support Articles (frontier)
- Performance KB Articles (frontier)
- Security KB Articles (frontier)
Frontier under this node: Connectivity Troubleshooting, Error Code Lookup, Performance KB Articles, Replica Set Support Articles, Security KB Articles