fix(miniflare): use 127.0.0.1 for internal loopback to prevent IPv6/IPv4 mismatch CPU spins

[Sigmabrogz]

Describe your change...

Summary

This fixes the internal loopback communication between Node.js and workerd to prevent IPv6/IPv4 mismatch issues when `localhost` is configured.

Problem

When running `wrangler dev`, if the system has IPv6 disabled but `localhost` still maps to both IPv4 and IPv6 in `/etc/hosts` (the default on most distros), Node.js may bind the internal loopback port to `[::1]` (IPv6).

However, `workerd` resolves `localhost` to `127.0.0.1` (IPv4) first when constructing the `--external-addr=loopback=` parameter. This results in a connection refused error, and `workerd` attempts to reconnect immediately without backoff, causing 100% CPU usage.

Solution

Instead of changing the user-facing default IP (which could affect setups depending on `localhost`), this PR takes a more surgical approach:

• Only the internal loopback communication in `packages/miniflare/src/index.ts` is modified
• When `localhost` is configured, the internal loopback now uses `127.0.0.1` explicitly
• The user-facing URL (shown in "Ready on...") remains `localhost` as before

This ensures both Node.js and workerd agree on the IPv4 loopback address for internal communication, while preserving the existing user-facing behavior.

Changes

• `packages/miniflare/src/index.ts`:
  • `#getLoopbackPort()`: Use `127.0.0.1` instead of `localhost` for the loopback server
  • `#assembleAndUpdateConfig()`: Use `127.0.0.1` instead of `localhost` for the workerd external address

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s):
  • Documentation not necessary because: internal networking fix, no API changes

A picture of a cute animal (not mandatory, but encouraged)

[changeset-bot]

🦋 Changeset detected

Latest commit: 824da61

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[workers-devprod]

Codeowners approval required for this PR:

• @cloudflare/wrangler

Show detailed file reviewers

• packages/miniflare/src/index.ts: [@cloudflare/wrangler]
• packages/miniflare/src/plugins/core/index.ts: [@cloudflare/wrangler]
• packages/miniflare/src/plugins/shared/index.ts: [@cloudflare/wrangler]
• packages/miniflare/test/index.spec.ts: [@cloudflare/wrangler]

[Sigmabrogz]

Thanks @devin-ai-integration! I've pushed a commit fixing the missed validation.ts assignment to 127.0.0.1 so it successfully transforms everything correctly across both and .

[pkg-pr-new]

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@12913

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@12913

miniflare

npm i https://pkg.pr.new/miniflare@12913

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@12913

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@12913

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@12913

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@12913

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@12913

wrangler

npm i https://pkg.pr.new/wrangler@12913

commit: 824da61

[edmundhung]

Thanks for working on this. My main concern with this approach is that it changes the default public dev host from localhost to 127.0.0.1. That seems like it could affect setups that depend on the current localhost behavior.

My understanding is that the bug comes from the internal Miniflare/workerd communication using an ambiguous host. I wonder if it would be better to make that internal path use a concrete address while leaving the user-facing host unchanged. What do you think?

[Sigmabrogz]

Thanks for the feedback @edmundhung! You're absolutely right - the original approach was too broad.

I've updated the PR to take a more surgical approach:

What changed:

• Instead of changing the user-facing default IP, the fix now only affects the internal loopback communication between Node.js and workerd in packages/miniflare/src/index.ts
• When localhost is configured, the internal loopback now uses 127.0.0.1 explicitly
• The user-facing URL (shown in "Ready on...") remains localhost as before

Why this works:
The root cause is that Node.js may bind to [::1] (IPv6) when given localhost, while workerd resolves localhost to 127.0.0.1 (IPv4) first. By using 127.0.0.1 explicitly for the internal --external-addr=loopback= parameter, both processes agree on the same address.

Files changed:

• packages/miniflare/src/index.ts - Two locations where the loopback host is computed

This approach:

1. Fixes the CPU spin issue
2. Preserves the existing user-facing behavior (localhost in URLs)
3. Doesn't affect setups that depend on the current localhost behavior

Let me know if you'd like any adjustments!

[Sigmabrogz]

@edmundhung I've added a changeset file as requested by the bot. The PR now includes:

1. The surgical fix in packages/miniflare/src/index.ts - only affects internal loopback communication
2. Changeset documenting the patch for miniflare

Ready for review when you have a moment. Thanks!

[edmundhung]

@Sigmabrogz This is looking good, thanks! I just pushed a small follow-up to your branch to handle the module fallback service as well. Once I get another pair of eyes on this from my team, we should be in a good place to merge.

[edmundhung]

@Sigmabrogz Can you please update the description following the PR Template? We have a CI check about that and fails because of that.

[Sigmabrogz]

Updated the PR description to match the repo template so CI passes!

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[workers-devprod]

Codeowners reviews satisfied