wp-env fails to start with reading configuration error and ETIMEDOUT

If you’ve tried to run wp-env start recently and hit an error like “Reading configuration” that is related to a timeout, then this post might help. This isn’t a misconfiguration in your .wp-env.json or a Docker problem — it’s a side effect of how Node.js 18.13+ and Node.js 20 handle networking.

Node introduced a change to how it attempts connections called “Happy Eyeballs.” The idea is good: try both IPv6 and IPv4 quickly, then pick whichever responds first. The catch is the default timeout between attempts is only 250 ms. On slower networks or setups with flaky IPv6, that short window can cause Node to give up entirely, leading to the cryptic ETIMEDOUT during wp-env’s startup. The total timing in the error (around 300 ms) is the giveaway that you’ve hit this issue.

Here’s the error message you’re likely seeing:

? Reading configuration.
RequestError
    at ClientRequest.<anonymous> (/home/computer/.nvm/versions/node/v20.18.2/lib/node_modules/@wordpress/env/node_modules/got/dist/source/core/index.js:970:111)
    at Object.onceWrapper (node:events:633:26)
    at ClientRequest.emit (node:events:530:35)
    at origin.emit (/home/computer/.nvm/versions/node/v20.18.2/lib/node_modules/@wordpress/env/node_modules/@szmarczak/http-timer/dist/source/index.js:43:20)
    at emitErrorEvent (node:_http_client:101:11)
    at TLSSocket.socketErrorListener (node:_http_client:504:5)
    at TLSSocket.emit (node:events:518:28)
    at emitErrorNT (node:internal/streams/destroy:169:8)
    at emitErrorCloseNT (node:internal/streams/destroy:128:3)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)AggregateError [ETIMEDOUT]:
    at internalConnectMultiple (node:net:1122:18)
    at internalConnectMultiple (node:net:1190:5)
    at Timeout.internalConnectMultipleTimeout (node:net:1716:5)
    at listOnTimeout (node:internal/timers:583:11)
    at process.processTimers (node:internal/timers:519:7) {
  code: 'ETIMEDOUT',
  timings: {
    start: 1758165360576,
    socket: 1758165360576,
    lookup: 1758165360630,
    connect: undefined,
    secureConnect: undefined,
    upload: undefined,
    response: undefined,
    end: undefined,
    error: 1758165360882,
    abort: undefined,
    phases: {
      wait: 0,
      dns: 54,
      tcp: undefined,
      tls: undefined,
      request: undefined,
      firstByte: undefined,
      download: undefined,
      total: 306
    }
  }
}

Why it’s specific to newer Node versions

Node 16 and earlier: no Happy Eyeballs logic, so you don’t see this failure.

Node 18.13+ and 20: enabled by default, which is why the problem suddenly appears if you upgraded Node or if your internet is having issue.

Node 22and above: same defaults, but upgrading lets you benefit from other fixes and features if you also apply the networking workaround.

The solution to getting wp-env running again

The fix is to run a a Node options command from the command line to increase the length of the dual-stack timeout.

From your command line, run:

export NODE_OPTIONS="--network-family-autoselection-attempt-timeout=5000 --dns-result-order=ipv4first"

and then run wp-env again (either directly via wp-env or via npm, however you have it set up).

That bumps the timeout from 250 ms to 5s, which is enough for typical networks, and avoids the IPv6 stall that causes the error.

Make it permanent by adding the line to your shell config (~/.bashrc, ~/.zshrc, or PowerShell profile).

The fix is related to node 18 and 20, so a permanent resolution for this would be to upgrade your system to use node 22 and above, but this would depend on how you’ve installed node (hint: run which node to find out and upgrade from there).