[Bug][Desktop 0.2.1-rc.5] Startup fatal "bad port": OS-assigned host port can land on the Fetch spec's forbidden-port list

[kaokxoas]

Summary

On startup the desktop shell spawns the embedded host with --port 0, so the OS picks the port. On machines whose dynamic port range reaches into the low IANA range, the OS can assign a port that is on the WHATWG Fetch forbidden port list (badPorts in undici). The shell then performs its one-time cookie handshake with fetch() on that URL, and undici rejects it locally — no packet is ever sent:

TypeError: fetch failed  ->  cause: Error: bad port  (makeNetworkError)

hostCookie = await authenticateWebHost(ready.url) throws, the backend controller treats it as fatal, and the user gets the "DeepSeek Harness is unavailable" dialog. That dialog's third button is Disable third-party plugins, so the incident reads as "a plugin broke my install" — the plugins are unrelated.

Every restart draws a new random port, so it almost always recovers. That is why it is rare and easy to dismiss — but it is a real startup-fatal path, and it costs the user a scare plus a support round each time it fires.

Environment

App	@deepseek-ai/dsh-desktop 0.2.1-rc.5 (dshBuildCommit d4db512a969fccf0c5cc7ec8fe38e9c1d27af916)
OS	Windows, win32 x64
Runtime	Electron 44.7.0 · Node 24.21.0
Locale	en
Host spawn	--port 0

Observed

%APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-2026-11-04T04-05-18-460Z-host.log:

time: 2026-11-04T04:05:18.460Z
source: host   phase: startup
[TypeError: fetch failed] {
  [cause]: Error: bad port
      at makeNetworkError (node:internal/deps/undici/undici:11841:35)
      at mainFetch (node:internal/deps/undici/undici:13224:22)
      at fetching (node:internal/deps/undici/undici:13211:7)
      at fetch (node:internal/deps/undici/undici:17857:10)
      at fetch (node:internal/bootstrap/web/exposed-window-or-worker:83:12)
      at authenticateWebHost (file:///.../resources/app/lib/main.js:8289:25)
      at Object.start (file:///.../resources/app/lib/main.js:12250:24)
}

renderer console: no error-level output captured.

Root cause chain

1. dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/index.js:238 — the host is spawned with "--port", "0", i.e. any port the OS hands out.
2. .../dsh-desktop-host/lib/index.js:342 — the ready URL is built as http://127.0.0.1:${ctx.webServer.port}. dsh-host-webserver/lib/index.js:293 returns this.listenedPort, assigned at :473 from this.server.address().port, so the port really is bound and the host has no reason to distrust it.
3. resources/app/lib/main.js:8289 — authenticateWebHost(url) calls fetch(url, { redirect: "manual" }); :12250 — hostCookie = await authenticateWebHost(ready.url).
4. dsh/node_modules/undici/lib/web/fetch/constants.js — badPorts (79 entries) holds the classic unsafe ports, including 1719 1720 1723 2049 3659 4045 4190 5060 5061 6000 6566 6665-6669 6679 6697 10080; lib/web/fetch/index.js:588 turns that into makeNetworkError('bad port') before any socket work. Max value is 10080; '0' is deliberately absent, so --port 0 itself is fine — only the result can be bad.
5. Windows default dynamic range is 49152–65535, which never collides. But machines carrying an explicit/legacy netsh int ipv4 set dynamicport tcp start=... num=... (ours: start=1024 num=13977 => 1024–15000) hand out low ports, and those do collide. Worth adding: even if the handshake were fixed, Chromium refuses to navigate to a bad port (ERR_UNSAFE_PORT), so this has to be prevented at bind time, not only in the fetch call.

Measured overlap on the affected machine: 19 of 13977 ports => ~0.14 % per launch (about 1 in 735 starts), which matches how intermittent it looked.

Reproduction

Deterministic on Windows (admin shell):

netsh int ipv4 set dynamicport tcp start=1024 num=13977

then keep launching the desktop app until the assigned port falls in the overlap; it fails immediately with bad port. To make it immediate, force the host onto a forbidden port (a wrapper passing --port 6000, or stub webServer.port to 6000) and start the app: authenticateWebHost throws with exactly the trace above.

Suggested fixes (any one is sufficient)

1. Verify after bind. Keep the ephemeral assignment, but if the bound port is in the forbidden set, close and re-listen. The check belongs in dsh-host-webserver immediately after :473 — one small block, and it also protects the dsh web -> browser handoff on hostile ranges.
2. Pick explicitly. Enumerate candidates, skip the forbidden set, pass --port <n>, and retry a bounded number of times on EADDRINUSE in dsh-desktop-host.
3. Give the user a hint. In resources/app/lib/main.js:8390-8440 the fatal dialog only special-cases /\blisten EADDRINUSE\b/u (restart-only, plus the "another DSH instance is running" copy). A bad port failure deserves the same treatment — offer Quit / Restart and say a retry normally succeeds — instead of pointing at plugins.

Workaround applied here

netsh int ipv4 set dynamicport tcp start=49152 num=16384   # revert: start=1024 num=13977

Raising the ephemeral range above 10080 empties the intersection with badPorts.

Pointers

• dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/index.js:238,342
• dsh/node_modules/@deepseek-ai/dsh-host-webserver/lib/index.js:293,473
• resources/app/lib/main.js:8289,12250,8390-8440 (fatal dialog), :7345 / :7512 (startupFailed copy, en/zh)
• dsh/node_modules/undici/lib/web/fetch/constants.js (badPorts), .../fetch/index.js:588

[kaokxoas]

Startup-failure cluster: one symptom, three distinct root causes

There are 100+ discussions filed with the same symptom — the desktop app refuses to start and shows desktop welcome: Web authentication failed / 「DeepSeek Harness 无法使用」. They are not one bug, and they cannot all be fixed by the same patch. One line of the crash log separates them.

Where the log is

• Windows: %APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*.log
• macOS: ~/Library/Application Support/@deepseek-ai/dsh-desktop/logs/crash-*.log
• Linux: ~/.config/@deepseek-ai/dsh-desktop/logs/crash-*.log

Look at the phase: startup entry and its [cause].

Crash-log signature	Root cause	Where it is tracked
TypeError: fetch failed → [cause]: Error: bad port	The OS-assigned host port fell on undici / Fetch's forbidden-port list; the shell's fetch() refuses before any packet is sent	this thread (#12098)
431 / Request Header Fields Too Large / maxHeaderSize / 16 KB / Cookie header overflow	dsh-auth-* cookies are minted per launch and never purged; after ~70 launches the request header exceeds Node's limit	#11133182, #11101173, #11397, #11374, #11408, #11034 (and the rest of the 431 family)
303 handshake succeeds but the cookie never sticks	net.fetch strips SameSite=Strict when following the 303 redirect	#11602

Two of the reports already noticed that the port changes from launch to launch (#11192000, #11624, #11410, #12080) and folded it into the cookie story. That observation is correct but it is a second mechanism: with a forbidden port the failure happens before the handshake, so no 431 is ever logged — and the port is what decides whether you get that error, not the cookie count. If your log shows bad port, you are in family C (this thread); if it shows 431 / header overflow, you are in family B.

Full symptom list for cross-referencing / duplicate closing:
https://github.com/deepseek-ai/deepseek-harness/discussions?discussions_q=%22Web+authentication+failed%22

If your crash log shows none of the three signatures above, paste the phase: startup entry — that would be a fourth family, and worth a separate thread rather than another duplicate of these.

[kaokxoas]

Census, and one adjacent thread worth fixing together

• The search link above is the authoritative duplicate list; it returns 71 threads as of 2026-11-04. Almost all of them are family B (431 / 16 KiB header). Family C — this thread — currently has no other report, and there is a reason: the bad-port path sends no HTTP request at all, so it produces no 431, no cookie overflow and no server-side log. Users experience it as "the app occasionally refuses to start and a retry fixes it", which rarely gets filed. The only artifact is the local crash log line cause: Error: bad port.
• Not a duplicate, but the same blast radius: [Recovery] "Disable third-party plugins" removes first-party bundles and wipes the user's profile patch #8766 — the fatal dialog's Disable third-party plugins recovery path deletes first-party bundles and wipes state. That is exactly the button offered for a bad-port startup failure, so a transient random-port collision can be turned into a damaged installation by following the dialog's own advice. The dialog and this bug should be handled together: any failure a plain restart resolves must not advertise a destructive action (suggestion 3 in the body).

For anyone arriving here from one of the 431 threads: your fix is to clear the accumulated dsh-auth-* cookies / ship the purge in the shell; the port assignment is a separate lever and fixing it will not make the 431 family go away.