Heuristic:Nightwatchjs Nightwatch Node 17 DNS IPv4 Workaround
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Debugging |
| Last Updated | 2026-02-12 01:00 GMT |
Overview
Nightwatch applies `dns.setDefaultResultOrder('ipv4first')` to work around a Node.js v17+ DNS resolution change that causes `ECONNREFUSED` errors when connecting to WebDriver on `localhost`.
Description
Starting with Node.js v17, the default DNS resolution order changed from IPv4-first to the OS-determined order (which often prefers IPv6). This means `localhost` may resolve to `::1` (IPv6) instead of `127.0.0.1` (IPv4). Since most WebDriver servers (ChromeDriver, GeckoDriver) listen only on IPv4 `127.0.0.1`, this mismatch causes `ECONNREFUSED` errors. Nightwatch applies the `dns.setDefaultResultOrder('ipv4first')` workaround at the HTTP module level to ensure all outgoing connections prefer IPv4 resolution.
Usage
This workaround is applied automatically by Nightwatch. No user action is required. However, if you encounter `ECONNREFUSED` errors when connecting to a local WebDriver server on Node.js 17+, this heuristic explains the root cause. The fix is already embedded in Nightwatch's HTTP request module and applies globally to all DNS lookups within the Nightwatch process.
The Insight (Rule of Thumb)
- Action: Nightwatch automatically calls `dns.setDefaultResultOrder('ipv4first')` on startup.
- Value: Prevents `ECONNREFUSED` errors when WebDriver server binds to IPv4-only `127.0.0.1`.
- Trade-off: IPv6-only WebDriver configurations would not work (extremely rare scenario). This workaround has no measurable performance impact.
- Scope: Applies to the entire Node.js process, not just Nightwatch HTTP requests.
Reasoning
The Node.js v17 change (see nodejs/node#40702) updated the `dns.lookup()` default behavior to use the OS resolver order. On most Linux and macOS systems with IPv6 enabled, `localhost` resolves to `::1` first. WebDriver server binaries (ChromeDriver, GeckoDriver, SafariDriver) typically bind only to `127.0.0.1:PORT` and do not listen on `[::1]:PORT`.
The `dns.setDefaultResultOrder('ipv4first')` API was introduced in Node.js v16.4.0 specifically to address this issue. Nightwatch checks for its existence before calling it for backward compatibility.
Code evidence from `lib/http/request.js:17-20`:
// To handle Node v17 issue. Refer https://github.com/nodejs/node/issues/40702 for details.
if (dns.setDefaultResultOrder && (typeof dns.setDefaultResultOrder === 'function')) {
dns.setDefaultResultOrder('ipv4first');
}
Related: retryable network errors from `lib/http/request.js:380-382`:
function isRetryableNetworkError(err) {
if (err && err.code) {
return (
err.code === 'ECONNABORTED' ||
err.code === 'ECONNRESET' ||
err.code === 'ECONNREFUSED' || // The error this workaround prevents
err.code === 'EADDRINUSE' ||
err.code === 'EPIPE' ||
err.code === 'ETIMEDOUT'
);
}
return false;
}