Skip to content

docs: add troubleshooting note for querySrv ECONNREFUSED on Windows#16342

Merged
vkarpov15 merged 2 commits into
Automattic:masterfrom
Ajay-Naik:docs/fix-srv-dns-windows-troubleshooting
Jun 28, 2026
Merged

docs: add troubleshooting note for querySrv ECONNREFUSED on Windows#16342
vkarpov15 merged 2 commits into
Automattic:masterfrom
Ajay-Naik:docs/fix-srv-dns-windows-troubleshooting

Conversation

@Ajay-Naik

Copy link
Copy Markdown
Contributor

What this PR does

Adds a troubleshooting note to docs/connections.md for the
querySrv ECONNREFUSED error when connecting to MongoDB Atlas
using mongodb+srv:// on Windows.

Why

This error affects many developers but is not currently documented
in Mongoose's connection docs. The fix (dns.setServers()) is
scattered across Medium articles and Stack Overflow but has no
official reference.

Root cause: Node.js uses its own DNS resolver (c-ares) which can
fail to resolve SRV records on Windows even when OS DNS works fine.
This was confirmed as a Node.js regression in v24.13.0:
nodejs/node#61453

Fix

Force Node.js to use Google's public DNS at the application level:
const dns = require('dns');
dns.setServers(['8.8.8.8', '8.8.4.4']);

References

@vkarpov15 vkarpov15 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this change belongs in the FAQ section faq.md not at the top of the connections docs. Do you think that is reasonable @Ajay-Naik ?

@Ajay-Naik

Ajay-Naik commented Jun 27, 2026 via email

Copy link
Copy Markdown
Contributor Author

@Ajay-Naik

Ajay-Naik commented Jun 27, 2026 via email

Copy link
Copy Markdown
Contributor Author

@vkarpov15 vkarpov15 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks 👍

@vkarpov15 vkarpov15 added this to the 9.7.4 milestone Jun 27, 2026
@vkarpov15 vkarpov15 added the docs This issue is due to a mistake or omission in the mongoosejs.com documentation label Jun 27, 2026
@vkarpov15 vkarpov15 merged commit bc2877f into Automattic:master Jun 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs This issue is due to a mistake or omission in the mongoosejs.com documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants