MongoDB KB Articles

Parent: MongoDB Expert Knowledge · Published reference · snapshot 2026-09-08 · skill misc-catch-all/references/mongodb-kb.md

↓ Facts as markdown all context files

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.

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mongodb-knowledge-base-article-index]

When to use this skill

Use this skill when you need to: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Match customer-reported symptoms to KB articles [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Find articles to share with customers (Public visibility only) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Research known issues, error codes, or resolution procedures [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Look up MongoDB behavior for replica sets, Atlas, sharding, performance, auth, or backups [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Generate code or advice grounded in official MongoDB KB guidance [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Diagnose error codes returned by mongod, mongos, or drivers [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Troubleshoot connectivity, authentication, replication, or sharding failures [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Run diagnostic commands and interpret their output [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Investigate Atlas-specific issues (IP allowlist, VPC peering, cluster scaling) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Analyze slow query plans and profiler output [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]
- Prepare escalation summaries with supporting diagnostic evidence [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-use-this-skill]

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 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#primary-keywords]

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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#context-file]
- Quick Reference section: top ~50 most broadly applicable articles, grouped by topic [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#context-file]
- Category Index: all articles grouped by concept (Configuration, Security, Performance, Replication, Sharding, etc.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#context-file]
- Each entry includes: article ID, title, summary, an internal URL field, shareable URL (support.mongodb.com), products, visibility (Public/Internal), and when-to-use guidance [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#context-file]

Usage guidance

Start at the Quick Reference section for common support scenarios [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#usage-guidance]
For specific topics, jump to the relevant category section [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#usage-guidance]
Always check Visibility before sharing a URL with a customer - only share Public articles [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#usage-guidance]
Use the shareableurl (support.mongodb.com) for customer-facing links [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#usage-guidance]
Use the internalurl field when referencing internally [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#usage-guidance]

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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#error-code-quick-reference]
Reference: https://www.mongodb.com/docs/manual/reference/error-codes/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#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(). [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#scram-authentication-troubleshooting]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#scram-authentication-troubleshooting]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#scram-authentication-troubleshooting]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#scram-authentication-troubleshooting]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#scram-authentication-troubleshooting]

`mongodb+srv://` (DNS seed list)

Verify SRV record exists: nslookup -type=SRV _mongodb._tcp.<hostname> [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mongodbsrv-dns-seed-list]
Verify TXT record exists: nslookup -type=TXT <hostname> [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mongodbsrv-dns-seed-list]
The SRV record must resolve to one or more A/AAAA records (not CNAMEs) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mongodbsrv-dns-seed-list]
Common failure: corporate DNS or VPN blocks SRV lookups -- fall back to mongodb:// with explicit hosts [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mongodbsrv-dns-seed-list]

`mongodb://` (standard)

Verify each host resolves: nslookup <host> or dig <host> [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mongodb-standard]
Test TCP connectivity: nc -zv <host> 27017 (or the configured port) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mongodb-standard]
If connecting through a load balancer or proxy, ensure it supports the MongoDB wire protocol (not HTTP) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mongodb-standard]

IPv6 vs IPv4

Node.js 17+ defaults to IPv6 DNS resolution. If the MongoDB server is IPv4-only: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ipv6-vs-ipv4]
- Set family=4 in the connection URI options [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ipv6-vs-ipv4]
- Or set the Node.js flag --dns-result-order=ipv4first [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ipv6-vs-ipv4]

Mechanism selection

MongoDB 4.0+ negotiates SCRAM-SHA-256 first, falls back to SCRAM-SHA-1 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mechanism-selection]
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 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mechanism-selection]
Fix: either recreate the user to include SHA-256 credentials, or force authMechanism=SCRAM-SHA-1 in the connection string [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#mechanism-selection]

Password special characters

Passwords containing @, :, /, % must be percent-encoded in the connection string: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#password-special-characters]

LDAP (PLAIN mechanism)

Requires Enterprise or Atlas [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ldap-plain-mechanism]
The mongod process must be able to reach the LDAP server on the configured port (default 389 or 636 for LDAPS) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ldap-plain-mechanism]
Set --setParameter authenticationMechanisms=PLAIN (in addition to SCRAM if both are needed) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ldap-plain-mechanism]
Debug with mongoldap tool to test LDAP connectivity and user mapping [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ldap-plain-mechanism]
Common failure: LDAP bind DN does not match the security.ldap.userToDNMapping regex [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ldap-plain-mechanism]

x.509 certificate authentication

The client certificate's subject (O, OU, DC attributes) must differ from the cluster member certificates [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#x509-certificate-authentication]
The certificate must be signed by the same CA specified in --tlsCAFile [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#x509-certificate-authentication]
The certificate must not be expired (openssl x509 -enddate -noout -in client.pem) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#x509-certificate-authentication]
The user must exist in the $external database with a username matching the certificate subject [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#x509-certificate-authentication]

Kerberos (GSSAPI)

The mongod host must have a valid keytab and be registered as a service principal [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#kerberos-gssapi]
The client must have a valid TGT (kinit user@REALM) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#kerberos-gssapi]
Clock skew > 5 minutes between KDC and mongod will cause authentication failure [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#kerberos-gssapi]
DNS must resolve both forward and reverse lookups for the mongod hostname [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#kerberos-gssapi]

Oplog management

Minimum recommended size: 24 hours of operations; 72 hours or more preferred [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#oplog-management]
Check current size: rs.printReplicationInfo() shows configured size and time range [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#oplog-management]
Resize without restart (4.0+): db.adminCommand({replSetResizeOplog: 1, size: <MB>}) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#oplog-management]
Oplog can grow beyond configured size to preserve the majority commit point [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#oplog-management]
Keep oplog size consistent across all data-bearing members [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#oplog-management]

Elections and failover

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

Rollback scenarios

Rollback occurs when a former primary had writes that were not replicated to the new primary [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#rollback-scenarios]
Data preserved: rollback data is written to <dbpath>/rollback/<ns>/<timestamp>.bson [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#rollback-scenarios]
Prevent rollbacks: use w: "majority" write concern (guaranteed no rollback on committed writes) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#rollback-scenarios]
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 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#rollback-scenarios]
Inspect rollback files: bsondump <rollback-file>.bson [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#rollback-scenarios]

Initial sync

Triggered when a new member joins or a member's data is too stale [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#initial-sync]
The sync source must have an oplog covering the entire duration of the initial sync [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#initial-sync]
Monitor progress: rs.status().members[n].initialSyncStatus (4.4+) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#initial-sync]
If initial sync fails repeatedly, increase oplog size on the sync source and ensure network stability [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#initial-sync]
For large datasets, consider restoring from a backup instead of initial sync (faster and less load on the source) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#initial-sync]

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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#chunk-migration-failures]
Insufficient disk space: The destination shard must have free space at least equal to the chunk size. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#chunk-migration-failures]
Replication lag on destination: If secondaries on the destination shard lag, migration waits for _secondaryThrottle to be satisfied. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#chunk-migration-failures]
Orphaned documents: After a failed migration, orphaned documents may remain. Run cleanupOrphaned to remove them. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#chunk-migration-failures]

StaleConfig errors

Occur when a mongos has outdated routing metadata [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#staleconfig-errors]
The driver automatically retries most StaleConfig errors [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#staleconfig-errors]
Persistent StaleConfig: run db.adminCommand({flushRouterConfig: 1}) on the affected mongos [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#staleconfig-errors]
After adding/removing shards or resharding, all mongos instances should refresh their metadata [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#staleconfig-errors]

Jumbo chunks

A chunk is marked jumbo when it exceeds the configured chunk size (default 128 MB) and cannot be split [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#jumbo-chunks]
Jumbo chunks cannot be migrated by the balancer, causing uneven distribution [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#jumbo-chunks]
Diagnosis: db.getSiblingDB("config").chunks.find({jumbo: true}) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#jumbo-chunks]
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}}) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#jumbo-chunks]
Root cause: low-cardinality shard key producing many documents with the same key value [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#jumbo-chunks]

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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#shard-key-issues]
Low cardinality keys: few unique values lead to jumbo chunks that cannot be split. Choose a key with high cardinality. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#shard-key-issues]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#shard-key-issues]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#shard-key-issues]

Interpret explain output

Key fields in explain("executionStats"): [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#interpret-explain-output]
Examined-to-returned ratio: If totalDocsExamined / nReturned > 10, the query is scanning too many documents. Add a covering index or refine the query filter. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#interpret-explain-output]

IP access list (allowlist)

Every client IP must be in the project's IP Access List (Network Access in Atlas UI) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ip-access-list-allowlist]
0.0.0.0/0 allows access from anywhere (not recommended for production) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ip-access-list-allowlist]
Dynamic IPs (home ISP, serverless functions) require either 0.0.0.0/0 or a static IP solution (NAT gateway, VPN, bastion host) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ip-access-list-allowlist]
Changes to the IP access list take effect within 1-2 minutes [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ip-access-list-allowlist]
Atlas shared-tier (M0/M2/M5) does not support VPC peering; must use IP access list [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ip-access-list-allowlist]

VPC / network peering

Available on M10+ dedicated clusters [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#vpc-network-peering]
After creating a peering connection, you must also add the peered VPC CIDR to the IP Access List [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#vpc-network-peering]
The peering connection establishes network-level routing, but Atlas still enforces IP-based access control [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#vpc-network-peering]
For AWS: ensure the VPC route table includes a route to the Atlas CIDR [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#vpc-network-peering]
For GCP: VPC peering is automatic with network peering; no route table changes needed [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#vpc-network-peering]
For Azure: ensure the VNet address space does not overlap with the Atlas CIDR [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#vpc-network-peering]
Private endpoints (AWS PrivateLink, Azure Private Link, GCP Private Service Connect) are preferred over peering for production [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#vpc-network-peering]

Atlas connection troubleshooting checklist

Verify cluster is deployed and status is "Active" in the Atlas UI [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
Confirm the database user exists and has the correct roles [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
Check the IP Access List includes the client's current public IP [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
Test DNS resolution: nslookup <cluster-hostname>.mongodb.net [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
Test TCP connectivity: nc -zv <cluster-hostname>.mongodb.net 27017 [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
Verify the connection string uses mongodb+srv:// with the correct cluster hostname [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
For VPC peering: confirm the peering connection status is "Active" and CIDR is in the access list [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
For private endpoints: confirm the endpoint status is "Available" in both Atlas and the cloud provider [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
Check TLS: Atlas requires TLS by default; ensure tls=true in the connection string (or ssl=true for older drivers) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]
Check driver compatibility: verify the driver version supports the MongoDB server version on the Atlas cluster [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#atlas-connection-troubleshooting-checklist]

FTDC (Full-Time Diagnostic Data Capture)

Enabled by default on all MongoDB deployments [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ftdc-full-time-diagnostic-data-capture]
Captures serverStatus, replSetGetStatus, and other metrics every 1 second [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ftdc-full-time-diagnostic-data-capture]
Stored in <dbpath>/diagnostic.data/ [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ftdc-full-time-diagnostic-data-capture]
Analyze with mongod --ftdc tools or third-party tools like keyhole, mdiag [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ftdc-full-time-diagnostic-data-capture]
For Atlas: download FTDC data from the Atlas UI under the cluster's "..." menu [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ftdc-full-time-diagnostic-data-capture]
FTDC does not capture query shapes or slow queries -- use the profiler for those [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#ftdc-full-time-diagnostic-data-capture]

Log structure (MongoDB 4.4+ structured logging)

MongoDB 4.4+ uses structured JSON logging. Key fields: [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#log-structure-mongodb-44-structured-logging]
- s: severity (F, E, W, I, D1-D5) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#log-structure-mongodb-44-structured-logging]
- c: component (ACCESS, COMMAND, CONTROL, NETWORK, QUERY, REPL, SHARDING, STORAGE, etc.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#log-structure-mongodb-44-structured-logging]
- id: message ID (stable across versions) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#log-structure-mongodb-44-structured-logging]
- ctx: context (connection ID, thread name) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#log-structure-mongodb-44-structured-logging]
- msg: human-readable message [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#log-structure-mongodb-44-structured-logging]
- attr: structured attributes (query shape, duration, planSummary, etc.) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#log-structure-mongodb-44-structured-logging]

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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#key-log-messages-to-watch]

When to escalate

Customer is experiencing data loss or corruption [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-escalate]
A node is in an unrecoverable state (repeated crash loop, ROLLBACK that never completes) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-escalate]
Performance degradation with no identifiable root cause after profiler and explain analysis [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-escalate]
Cluster-wide issues affecting availability (elections every few minutes, split-brain) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-escalate]
Atlas-specific issues that cannot be resolved through the UI or API (stuck scaling operations, billing anomalies) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#when-to-escalate]

Information to collect for escalation

MongoDB version: db.adminCommand({buildInfo: 1}).version [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Topology: standalone / replica set / sharded cluster; number of members; Atlas tier [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Server status snapshot: db.serverStatus() (full output) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Replica set status: rs.status() (if applicable) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Sharding status: sh.status() (if applicable) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
FTDC data: from <dbpath>/diagnostic.data/ or Atlas download [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Log excerpts: relevant log lines with timestamps (use structured JSON format) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Profiler output: db.system.profile.find().sort({ts: -1}).limit(20) for slow query issues [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Explain plans: db.coll.find({...}).explain("executionStats") for query performance issues [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Timeline: when the issue started, any recent changes (deployments, config changes, scaling) [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Impact: number of users affected, error rates, latency percentiles [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]
Reproduction steps: if the issue is reproducible [archived source: https://llms-explorer.com/sources/mdb-context-hub/mongodb-kb/#information-to-collect-for-escalation]

References

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

Where this helps

Triaging a customer-reported symptom during a support case by matching the error message or behavior against a known KB article instead of researching from scratch. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Preparing an escalation summary that needs the standard diagnostic evidence checklist (FTDC, logs, explain plans, topology) gathered before handing off. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Deciding whether a KB article is safe to share with a customer, based on its Public vs Internal visibility flag. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Diagnosing an authentication failure (SCRAM, LDAP, x.509, Kerberos) by working through the specific failure-mode checklist for that mechanism. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

How to apply this

Start any new customer symptom at the Quick Reference section rather than searching the full ~2,717-article index cold. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Always check an article's visibility field before pasting its URL into a customer-facing message — only Public articles get the shareable support.mongodb.com link. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
When escalating, gather the standard evidence set up front (version, topology, serverStatus, FTDC, relevant logs, explain plans) so the escalation doesn't bounce back for missing information. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Cross-reference log message IDs against the target deployment's MongoDB version before treating them as stable signals, since only a small number are reliably stable across versions. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Antipatterns

Sharing an Internal-visibility KB article's URL with a customer instead of confirming it's Public first — an easy way to leak internal-only guidance. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Treating FTDC as a source of slow-query detail — FTDC captures serverStatus-style metrics every second but not query shapes, so slow-query diagnosis still needs the profiler. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Rebooting multiple secondaries simultaneously in a 3-member replica set, which can cause the primary to step down from loss of quorum. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Relying on a log message ID as a stable signal across MongoDB versions without checking it against the target deployment first — most IDs are not guaranteed stable release to release. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Known issues

Dynamic client IPs (home ISPs, serverless functions) don't fit cleanly into Atlas's IP Access List model — the practical options are 0.0.0.0/0 (not recommended for production) or a static-IP solution like a NAT gateway or bastion host. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
VPC peering and private endpoints are only available on M10+ dedicated clusters, so shared-tier (M0/M2/M5) deployments must rely entirely on IP access lists for network access control. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Large rollback scenarios changed materially at MongoDB 5.0+ — the legacy "rollback via refetch" path had a 300MB shutdown threshold, while the newer "recover to a timestamp" approach has no fixed rollback-size limit, so older troubleshooting guidance doesn't fully apply to newer versions. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Jumbo chunks caused by a low-cardinality shard key cannot be migrated by the balancer and require manual splitting plus clearing the jumbo flag — the underlying cardinality problem doesn't self-resolve. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.

Children

Error Code Lookup (frontier, viability 3.13 / 5, below research gate)
Connectivity Troubleshooting (frontier, viability 4.15 / 5)
Replica Set Support Articles (frontier, viability 2.42 / 5, below research gate)
Performance KB Articles (frontier, viability 2.58 / 5, below research gate)
Security KB Articles (frontier, viability 2.58 / 5, below research gate)

Frontier under this node: Connectivity Troubleshooting (4.15), Error Code Lookup (3.13), Performance KB Articles (2.58), Replica Set Support Articles (2.42), Security KB Articles (2.58)

← the whole tree · 3D view· how to read this page