Connectivity Troubleshooter 🕵️

[tnaum-ms]

Connectivity Troubleshooter for Failed DocumentDB and MongoDB Connections

Description:

When a connection attempt fails in the DocumentDB for VS Code extension, users are currently left with a brief error message, often with limited insight into what went wrong. This feature introduces a Connectivity Troubleshooter that helps users quickly identify common issues when trying to connect to MongoDB or DocumentDB endpoints.

Instead of guessing or manually testing, users will be able to activate a built-in tool that runs a sequence of automatic checks based on the provided connection string and reports clear diagnostics.

---

Proposed Functionality:

Upon a failed connection attempt, the user will be prompted to "Run Troubleshooter", which performs the following diagnostic steps:

1. Validate Connection String Format

   • Checks if the connection string is syntactically valid and contains expected components (scheme, host, port, credentials, options).

2. Check System Online Status (Optional, warning only)

   • Pings a known, reliable public host (e.g., 8.8.8.8, etc.).
   • If unreachable, displays a warning such as: "Your system may be offline or unable to reach external hosts."
   • This check does not block further diagnostics but provides helpful context in offline scenarios.

3. Parse and Resolve Hostname

   • Extracts the hostname from the URI and attempts DNS resolution.
   • For SRV-style URIs (mongodb+srv://), performs SRV and TXT record lookups.
   • Fails early if resolution doesn't return valid addresses.

4. Ping Target Port

   • Verifies whether the specified host and port are reachable via TCP.
   • Distinguishes between connection timeout and immediate rejections.

5. Inspect Network Access

   • Detects if firewall, antivirus, VPN, or proxy settings might be blocking outbound traffic to the target host.
   • Uses heuristics from previous steps to determine if network conditions are interfering.

6. Credential Completeness Check

   • Ensures that the connection string includes necessary authentication details, if required.

7. Connection and Permissions Verification

   • Attempts to establish a real connection using the full connection string.
   • Diagnoses errors including authentication failures, TLS certificate issues, and handshake problems.
   • If authentication succeeds, attempts to list databases using the authenticated user.
   • If permissions are insufficient, a clear message will be shown explaining the failure.

8. Suggest External Investigation

   • If all internal checks pass but the connection still fails, the user is advised to:
     • Verify server-side access controls (IP allowlists, firewall rules).
     • Check for misconfigured authentication, TLS certificates, or network routing.
     • Contact their cloud provider (e.g., Azure Cosmos DB, MongoDB Atlas) for further troubleshooting assistance.
   • A message like the following could be shown:
     "Everything looks correct on your local system. The issue may lie in the server-side configuration. Please review your cluster’s access controls or consult your provider’s support documentation."

---

Expected Behavior:

• If a connection fails, the user will be able to launch the troubleshooter via a prompt or command palette entry.
• A step-by-step diagnostic output will be shown, with clear pass/fail indicators and helpful messages.
• For failed checks, actionable suggestions will be provided.
• If all checks pass but the connection still fails, the user is guided to investigate external configuration issues.

---

Additional Considerations:

• Results should be presented in a readable format, potentially using a React-based WebView or a structured terminal-like output.
• Troubleshooter could be built to work even outside of failed connection flows, e.g., as a command available from the Command Palette for any saved connection.
• Diagnostic checks should not send or store any credentials, only the structural and network-relevant parts of the connection string are parsed.
• This could be the basis for future telemetry-based pattern detection, helping us identify common root causes users encounter.
• The implementation should be portable so that the core logic can be released as a standalone command-line tool.

[LuchiLucs]

I would like this feature as well to get to know which is the expected connection string template and supported keys. Exporting the connection string URI from Studio 3T does not work out the box, and I don't know if tls tunning is supported at the moment.

[tnaum-ms]

Packaging and release plan

• Please put the core troubleshooter logic into a standalone npm package (for example @<org>/connectivity-troubleshooter).

  • Keep it UI-agnostic so it can be reused by multiple clients.
  • The package should expose a simple way to run checks and return a structured result that a UI can present (document-style output, and/or progress notifications).

• First integration should be the DocumentDB for VS Code extension.

  • The extension owns the UX (prompt, webview/terminal output), and calls the shared npm package.

• After the core feature set is implemented and stable, we should also ship a command line utility.

  • This should be a separate npm package (for example @<org>/connectivity-troubleshooter-cli) that wraps the same core package.
  • Goal: same checks, different presentation (CLI output).

[tnaum-ms]

Extra checks to add (common real-world failures)

These are checks that often explain “it works for others but not for me” connection failures.

1. IP allowlist / network access list

   • If the target looks like MongoDB Atlas (or similar managed service) and the connection times out, add a clear hint to verify the project/cluster IP access list (allowlist).
   • Reference: MongoDB Atlas docs explicitly call out “IP address not in IP Access List” as a common cause.
     https://www.mongodb.com/docs/atlas/troubleshoot-connection/

2. More explicit DNS failure mapping

   • When hostname resolution fails, show the common error names and what they usually mean:
     • ENOTFOUND: hostname cannot be resolved (wrong host / DNS issue).
     • EAI_AGAIN: temporary DNS lookup failure / timeout.
   • References:
     • Node.js issue discussion of EAI_AGAIN meaning a temporary DNS failure:
       The getaddrinfo EAI_AGAIN error again nodejs/node#15780
     • Community guidance on EAI_AGAIN as DNS lookup timeout / proxy/network related:
       https://stackoverflow.com/questions/40182121/whats-the-cause-of-the-error-getaddrinfo-eai-again

3. TLS trust chain / CA bundle checks

   • If TLS is required and the handshake fails, guide users to verify they are using the correct CA bundle and that the cluster/app certificates are up to date.
   • References:
     • Amazon DocumentDB “Troubleshooting connection issues”:
       https://docs.aws.amazon.com/documentdb/latest/developerguide/troubleshooting.connecting.html
     • AWS guidance on updating CA certificate bundles:
       https://docs.aws.amazon.com/documentdb/latest/developerguide/ca_cert_rotation.html
     • AWS Knowledge Center note about using the latest public certificate bundle when TLS is activated:
       https://repost.aws/knowledge-center/documentdb-cannot-connect

4. System clock / time skew hint (TLS)

   • When TLS errors indicate “not yet valid” or “expired”, point to incorrect local time as a possible cause (common on dev VMs and some corporate images).

5. Captive portal / proxy / VPN interference

   • If “online check” passes but SRV/TXT lookups or target TCP connect fails only on certain networks, hint at proxy/VPN/corporate DNS constraints as a likely cause.

6. Clarify timeout vs immediate refusal

   • When the port probe times out: likely routing/firewall/security group/allowlist.
   • When it is immediately refused: likely service not listening, wrong port, or local firewall.

[rysiekg]

Would it be possible to check whether private endpoint is configured and whether the connection is using it?