Background

Users connecting to MongoDB Atlas via mongodb+srv:// on Windows frequently hit:

  Error: querySrv ECONNREFUSED _mongodb._tcp.<cluster>.mongodb.net
  

This has become a highly recurrent community problem. Recent examples:

• Reddit (June 2026) — "I spent 4 days debugging MongoDB's ECONNREFUSED
error" — user misattributed the bug to the internet service provider (ISP) but fixed it with dns.setServers() as a workaround.
• MongoDB Community Forum thread
• alexbevi.com blog post
• Internal KB article kA5Ue0000002r1pKAA — Resolving the Node.js "QuerySrv ECONNREFUSED" Error Connecting to Atlas From Windows

The root cause is a Node.js issue/regression on Windows where dns.resolveSrv does not use the system resolver. It was patched in Node.js PR #61453 and shipped in v25.6.1, v24.14.0, and v20.20.1.

However, multiple users have reported the same symptom, suggesting low awareness or the fix does not cover all edge cases, or has regressed. The driver should be proactive on behalf of users rather than relying on the upstream fix and awareness alone, affected users today have no in-product signal pointing them at the right cause.

Proposed solution

When an SRV or TXT lookup rejects with ECONNREFUSED, check the runtime fingerprint:

• process.platform === 'win32'
• process.versions.node falls in a known-affected range (initial set: >=24.0.0 <24.14.0, >=20.0.0 <20.20.1, pre-25.6.1 — extensible as new
affected ranges emerge)

• If both match, wrap the error in a MongoAPIError whose message:
• Names the Node.js Windows DNS resolver regression as the likely cause
• Recommends upgrading to a patched Node.js release. 
• Points to additional resources for other workarounds
• Preserves the original error as cause

If either condition fails (different platform, patched Node, or unknown version), pass the original error through unchanged; ECONNREFUSED on other environments genuinely has other causes (firewalls, AV, real ISP blocking) and we must not mislead those users.

Acceptance criteria

• resolveSrv and resolveTxt paths in connection_string.ts and srv_polling.ts detect ECONNREFUSED and the runtime fingerprint.
• When both match, the thrown error is a MongoAPIError (or appropriate subclass) with a clear message referencing the Node.js regression and recommended next steps, and with the original error attached as cause.
• When either does not match, behavior is unchanged — original error propagates as-is.
• The affected-version list is centralized in a single constant for easy maintenance as new affected ranges are reported.
• Unit tests cover:
  • matching fingerprint → wrapped error;
  • non-Windows → unchanged;
  • patched Node → unchanged;
  • non-ECONNREFUSED DNS error → unchanged.

Other alternatives considered

The following alternatives were evaluated

References

• Node.js PR #61453 — upstream fix
• NODE-6451 — existing DNS retry logic (companion behavior)
• NODE-6640 — Add custom DNS Resolver to Node Driver (related, separate)
• Internal KB kA5Ue0000002r1pKAA — Windows querySrv ECONNREFUSED troubleshooting