Skip to content

fix: resolve localhost to 127.0.0.1 in browserUrl and wsEndpoint#1821

Closed
yiidtw wants to merge 1 commit intoChromeDevTools:mainfrom
yiidtw:fix/resolve-localhost-to-ipv4
Closed

fix: resolve localhost to 127.0.0.1 in browserUrl and wsEndpoint#1821
yiidtw wants to merge 1 commit intoChromeDevTools:mainfrom
yiidtw:fix/resolve-localhost-to-ipv4

Conversation

@yiidtw
Copy link
Copy Markdown

@yiidtw yiidtw commented Apr 6, 2026

Summary

On macOS, dns.lookup('localhost') non-deterministically resolves to ::1 (IPv6) or 127.0.0.1 (IPv4) depending on network state. Chrome's debug port typically binds only one address family, causing intermittent connection failures when users pass --browserUrl http://localhost:9222 or --wsEndpoint ws://localhost:9222/....

This PR adds a resolveLocalhostToIPv4() helper that replaces localhost with 127.0.0.1 in both the browserUrl and wsEndpoint coerce functions, matching Chrome's default IPv4 binding.

Changes

  • Add resolveLocalhostToIPv4(url) — regex replace of //localhost: and //localhost/ with //127.0.0.1
  • Apply in browserUrl coerce (after URL validation)
  • Apply in wsEndpoint coerce (after URL/protocol validation)
  • Update existing browserUrl test to expect 127.0.0.1
  • Add 5 new tests: localhost resolution (browserUrl, wsEndpoint), case-insensitive LOCALHOST, preserve explicit 127.0.0.1, preserve explicit [::1]

Test plan

  • All existing tests pass with updated expectations
  • New tests cover: lowercase localhost, uppercase LOCALHOST, already-127.0.0.1, explicit IPv6 [::1], wsEndpoint localhost

On macOS, Node.js dns.lookup('localhost') non-deterministically resolves
to ::1 (IPv6) or 127.0.0.1 (IPv4) depending on network state. Chrome's
debug port typically binds only one address family, causing intermittent
connection failures when users pass --browserUrl http://localhost:9222.

This adds a resolveLocalhostToIPv4() helper that normalizes localhost to
127.0.0.1 in both --browserUrl and --wsEndpoint coerce functions, while
preserving explicit 127.0.0.1 and [::1] addresses.
@nroscino
Copy link
Copy Markdown
Contributor

nroscino commented Apr 9, 2026

Hi @yiidtw!
I tried reproducing the issue but I wasn't able to. I recommend using --browserUrl=http://127.0.0.1:9222 if it happens to be unstable for you using localhost.
Thank you!

@nroscino nroscino closed this Apr 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants