Windows: server.host 'localhost' binds IPv6 only; proxy to localhost:port fails with ECONNREFUSED/ETIMEDOUT

[bayuwicaksono-obs]

Describe the bug

On Windows, a Vite dev server configured with server.host: 'localhost' can listen only on IPv6 ([::1]:port).

When another Vite app proxies to http://localhost:port, Node often connects via IPv4 (127.0.0.1), so proxy requests fail.

In the browser this often appears as:

TypeError: Failed to fetch dynamically imported module

even though the target module path is valid.

Reproduction

Environment

• OS: Windows 10/11 (build 26200)
• Node: v20.x
• Vite: 5.4.21
• Package manager: npm / pnpm

Setup

App A (target), vite.config.ts:

export default defineConfig({
  server: {
    port: 5002,
    host: 'localhost',
  },
});

App B (proxy / hub), vite.config.ts:

export default defineConfig({
  server: {
    port: 5000,
    proxy: {
      '/front-office': {
        target: 'http://localhost:5002',
        changeOrigin: true,
        ws: true,
      },
    },
  },
});

Steps

1. Start App A (vite, port 5002)
2. Start App B (vite, port 5000)
3. Open http://localhost:5000/front-office/
4. Navigate to a route with lazy / dynamic imports

Observed

• Hub / proxy logs:
  • http proxy error ... AggregateError [ECONNREFUSED]
  • http proxy error ... AggregateError [ETIMEDOUT]
• Browser:
  • Failed to fetch dynamically imported module: http://localhost:5000/front-office/@fs/.../index.ts

Network check on Windows

netstat -ano | findstr :5002
# LISTENING on [::1]:5002 (IPv6 only)

curl http://[::1]:5002/front-office/      # 200
curl http://127.0.0.1:5002/front-office/  # fails

Expected behavior

Proxying to http://localhost:5002 should work reliably on Windows when App A is running.

Actual behavior

Proxy requests fail intermittently or consistently because App A is reachable on IPv6 but not IPv4.

Workaround

Set the target app host to 0.0.0.0 (or true):

server: {
  port: 5002,
  host: '0.0.0.0',
}

After this:

• 127.0.0.1:5002 works
• hub proxy to localhost:5002 works

Why this matters

server.host: 'localhost' is a common setup. Monorepo setups with a hub app and multiple Vite apps behind a proxy are common, and this failure mode is hard to debug because the browser error points at module import paths, not networking.

Suggested improvements

1. Document Windows localhost IPv4 / IPv6 behavior for server.host
2. Warn when dev server is IPv6-only but proxy / client uses localhost
3. Consider a safer default for Windows proxy / monorepo workflows

Additional context

This is not an application code failure: production build succeeds, and direct access to the target port over IPv6 works before the workaround.

[DaZuiZui]

Thanks for the report. I traced both sides of this path, and I don't think the current evidence establishes a Vite bug yet.

Vite passes server.host unchanged to Node's httpServer.listen(). Therefore, if Windows resolves localhost to ::1, Node creates a listener on ::1; host: 'localhost' has never meant “listen on both 127.0.0.1 and ::1”. Vite intentionally stopped overriding localhost DNS resolution in #8642 so that Vite and other Node tools resolve it consistently. Changing localhost to listen on both families was also discussed in #18469 and declined because it would change the existing contract and widen the listening scope; multiple-host support is tracked separately in #16350.

The proxy path does not force IPv4 either: Vite 5 passes the target hostname to http-proxy, which delegates the connection to Node. Since Node 20.0.0, network-family auto-selection is enabled by default. Node looks up all available addresses and tries both families; the final AggregateError is emitted only when all attempts fail. I also checked the relevant combination directly with Node 20.0.0 + http-proxy 1.18.1: with DNS forced to ipv4first, a target listening only on ::1, and a proxy target of http://localhost:<port>, the request still reached ::1 and returned 200. Vite 5.4.21 itself also contains the proxy-hmr integration test with two default-localhost Vite servers and a http://localhost:9617 proxy target; the Node 20 / Windows job for the v5.4.21 commit passed.

So, if [::1]:5002 is alive and returned 200 at the same time, an IPv4 refusal alone should not make the Node 20 proxy fail—the ::1 attempt should succeed. The dynamic-import error is only the browser-visible consequence of the failed proxy request, not its cause. The full AggregateError likely contains the missing clue (different launch environments/DNS settings, an unavailable target at request time, a custom agent, firewall behavior, or a different actual port).

Could you please reproduce this on a currently supported Vite version and provide a runnable minimal repository? Vite 5 is no longer supported. Please also run these in the launch environment of both apps and paste the results:

node -p "process.version"
node -p "require('dns').getDefaultResultOrder()"
node -e "require('dns').lookup('localhost',{ all: true }, console.log)"
node -p "require('net').getDefaultAutoSelectFamily()"
node -p "JSON.stringify(process.execArgv)"
$env:NODE_OPTIONS
node -e "require('http').get('http://localhost:5002/', r => console.log(r.statusCode)).on('error', e => console.dir(e, { depth: null }))"

Please include the complete error, especially AggregateError.errors and the attempted addresses.

For now, the narrow and deterministic workaround is to use the same explicit loopback family on both sides:

// IPv4
server: { host: '127.0.0.1', port: 5002, strictPort: true }
// proxy target: http://127.0.0.1:5002

// or IPv6
server: { host: '::1', port: 5002, strictPort: true }
// proxy target: http://[::1]:5002

0.0.0.0 also masks the mismatch, but it exposes the dev server on non-loopback interfaces and should not be the default fix.

If a current, minimal Windows reproduction shows that Vite discards a successful address selected by Node, the repair should be in the proxy connection path, with a Windows regression test for an IPv6-only target. Silently mapping localhost to a wildcard or dual listener would be the wrong direction because it is breaking and security-sensitive.