[Bug]: Server fails to bind on Windows 11 when HNS/Hyper-V invisibly reserves port 45456/45457 — error is swallowed, UI shows only "Failed to fetch"

[mhozic]

Has this been reported before?

• I have checked for existing reports of this issue

Repro steps

Summary

On Windows 11 with Hyper-V components active (WSL2, Docker Desktop, Windows Sandbox, or just Hyper-V itself), the Host Network Service can invisibly reserve TCP ports 45456 and/or 45457. When this happens, HTTP Toolkit's server process silently fails to bind, the desktop log reports a successful startup, and the UI shows repeated TypeError: Failed to fetch. Uninstalling, wiping %APPDATA%/httptoolkit and %LOCALAPPDATA%/httptoolkit*, and reinstalling do not fix it because the install is fine — only the ports are unreachable.

Related issues

This appears to be the Windows 11 / Hyper-V variant of a broader "server can't bind, UI shows 'Failed to fetch' with no actionable error" family:

• [Bug]: Can't start HTTP Toolkit: Permission denied 127.0.0.1:45456, Server crashed #611 — Windows 10, port 45456, EACCES. Same symptom, different OS-level cause (ACL/permission vs. port reservation). No diagnosis or workaround in thread.
• [Bug]: HTTP Toolkit is not starting #771 — Ubuntu 24.04, port 45457 "already in use" but lsof shows nothing. Same "phantom port" pattern on Linux.
• [Bug]: Desktop app stuck on "This is taking longer than normal" #530 — "Stuck on 'This is taking longer than normal'" — likely same UI-side symptom from various underlying bind failures.
• [Bug]: Server crashed with Error listen EADDRINUSE address in use 127.0.0.1:454 #390 (closed) — older EADDRINUSE report.

A single fix — catch and surface bind errors with platform-specific hints, plus dynamic port fallback — would close all of these.

Environment

• HTTP Toolkit desktop v1.26.0
• Windows 11 Pro 10.0.26200
• Hyper-V / WSL2 / Docker Desktop installed (any one is enough to trigger this)

Symptoms

Desktop log (--- Launching HTTP Toolkit desktop ---) shows the server reporting success:

Standalone server started in 6 ms
UI Bridge API server listening on \\.\pipe\httptoolkit-ctl
Server started in 14 ms
Total startup took 38 ms
Found JVM: 'java'
info: Server initialization failed TypeError: Failed to fetch
info: Server initialization failed TypeError: Failed to fetch
... (repeats forever)
info: TypeError: Failed to update a ServiceWorker for scope ('https://app.httptoolkit.tech/') with script ('Unknown'): Not found

But:

• Get-NetTCPConnection -OwningProcess <node pid> returns no sockets.
• netstat -ano | findstr 45456 returns empty.
• A direct test with the bundled node binary fails:

& 'C:\Program Files\HTTP Toolkit\resources\httptoolkit-server\bin\node.exe' -e "require('http').createServer().listen(45456,'127.0.0.1',()=>{}).on('error',e=>console.error(e))"

# Error: listen EADDRINUSE: address already in use 127.0.0.1:45456

• The port doesn't appear in netsh interface ipv4 show excludedportrange protocol=tcp (neither active nor persistent store).
• The same node.exe binds fine to port 9876 or any port the OS hasn't invisibly reserved.

So the OS reports the port as held, but nothing visible holds it. This is the known signature of Windows HNS / Hyper-V port reservations, which don't surface in any standard diagnostic tool.

Root cause

Windows 11's Host Network Service reserves TCP port ranges at boot for vEthernet/WSL2/Docker port forwarding. The ranges are picked semi-randomly and are not reported by netsh excludedportrange. When HNS happens to reserve 45456 or 45457, HTTP Toolkit can't bind, and the bind error is being silently swallowed by the server startup code ("Standalone server started" is logged before the actual listen() succeeds).

Workaround (for affected users)

Elevated PowerShell:

Stop-Service hns       -Force -ErrorAction SilentlyContinue
Stop-Service winnat    -Force -ErrorAction SilentlyContinue
Stop-Service vmcompute -Force -ErrorAction SilentlyContinue
Start-Service vmcompute -ErrorAction SilentlyContinue
Start-Service hns       -ErrorAction SilentlyContinue
Start-Service winnat

…or reboot. Either re-rolls HNS's reservations, after which HTTP Toolkit boots normally. Permanent immunization:

netsh int ipv4 add excludedportrange protocol=tcp startport=45456 numberofports=2 store=persistent

Suggested fixes

1. Surface the actual bind error in the UI. Right now listen() failures on 45456/45457 are silent — the desktop logs "Server started" before the bind has actually completed, and the only visible symptom is Failed to fetch from the UI. Catching EADDRINUSE and displaying it ("Port 45456 is held by something else — on Windows 11 this is typically Hyper-V / HNS; try restarting those services or rebooting") would have saved several hours of guessing in my case.

2. Pick a free port dynamically and pass it to the UI. The UI's CSP already includes both 45456 and 45457 — extending the fallback further, or having the desktop wrapper communicate the chosen port to the UI via the existing \\.\pipe\httptoolkit-ctl handshake, would make the app immune to HNS reservations entirely.

3. Document the workaround. A short troubleshooting note in the docs ("HTTP Toolkit won't start on Windows 11") pointing at the HNS restart and the permanent excludedportrange reservation.

Reproduction (probabilistic)

Cannot be reproduced on demand — the bug fires only when HNS happens to reserve 45456/45457 at boot. On the affected machine it took ~2 days of normal Windows 11 use before HNS shuffled into a layout that overlapped, after which the problem was 100% reproducible across reboots until the workaround was applied.

How often does this bug happen?

Every time

The desktop OS you're using

Windows 11

Details of other apps/devices

No response

Error screenshot

No response

Any other info?

No response

[pimterry]

Thanks @mhozic. As mentioned in #771 (comment) I now have a working prototype of a solution for fully dynamic port selection & coordination across the HTTP Toolkit components, which should solve all these issues in the general case. Releasing this takes a little time since there's independently updating components involved and every component needs to be updated to a version that can coordinate correctly, or the app as a whole will fail to start up at all. This is coming soon, watch this space.

[pimterry]

Fix for this is now live - if you download & install the latest HTTP Toolkit, it will automatically detect and configure a local port that's definitely available, so there's no more fixed ports in use anywhere.