DeepSeek Harness Web authentication failed cookie 431 fix

A DeepSeek Harness desktop install suddenly stops opening, and the only line in the log is desktop welcome: Web authentication failed. Reinstalling, switching accounts, and changing API keys all do nothing. In this family of cases the usual cause is not broken authentication: every launch adds another local dsh-auth-* cookie, and after roughly 70 rows the Cookie header exceeds Node's default 16,384-byte limit, so the host returns 431 before the welcome handler ever runs. This article skips generic "clear the cache" advice and follows a verifiable order: prove the header is over the limit, pick one recovery path, then deal with recurrence (#10831, #11366).

DeepSeek Harness: First, separate a real credential problem from a header problem

Web authentication failed is the shared error text of the welcome flow; both 401 and 431 land on that sentence. Only a 431 or header-size evidence proves cookie accumulation.

Split the three common situations before you reinstall anything:

1. Credential problem: usually happens during a model request, the log shows MISSING_CREDENTIAL, a 401, or a provider name, and the UI still opens.
2. Port or address problem: in a dsh web setup you did not use the token-bearing URL printed in the terminal, and the prompt explicitly asks you to reopen that URL.
3. Header overflow: the desktop window never appears, the log stops at connectDesktopWelcome, and reinstalling does not help — this is the case in this article.

Confirmation takes three steps:

1. Fully quit DSH, including the tray icon and any leftover background process; verify in Task Manager that no DeepSeek Harness process remains.
2. Locate the cookie database: on Windows it is %APPDATA%\@deepseek-ai\dsh-desktop\Network\Cookies; on macOS it is ~/Library/Application Support/@deepseek-ai/dsh-desktop/Network/Cookies.
3. Run SELECT COUNT(*) FROM cookies WHERE host_key LIKE '%127.0.0.1%' AND name LIKE 'dsh-auth-%'; in any SQLite client. A result near 70 is the answer.

DSH plugin: Root cause: the cookie name includes the port, so every launch adds a row

The cookie name is dsh-auth- plus base64url(sha256(host authority)). Because the desktop host uses a random port on every launch, the name is different each time; the write sets only a 30-day Max-Age and never deletes older names.

The chain has four steps:

1. The desktop app starts the local host on a random 127.0.0.1 port.
2. The welcome flow hashes the current authority into a cookie name and mints a new dsh-auth-*.
3. The browser cookie database stores rows by domain, path, and name; a new name is a new row, and old rows stay.
4. The next launch uses another port and adds another row. Around 70 rows, the Cookie header passes 16,384 bytes and the host answers 431.

The size is easy to check: the community measured about 226 bytes per entry (52-byte name + 1-byte equals sign + 173-byte value). 71 entries plus 70 ; separators come to 16,186 bytes, already over Node's default limit (#10828).

The important part: old cookies do not affect server-side validation. authenticate() only looks up the entry for the current port; the other 70 are pure header weight. So the answer to "will clearing old cookies break authentication" is no — the current launch mints a new one (#11366).

DeepSeek Harness: Recovery: three ways to clear, ordered by risk

The safest move is to move the whole Network/Cookies file aside; if you want to keep cookies for other sites, delete only the dsh-auth-* rows; use the header-limit workaround only when you need to get in and export data first.

Option 1: Move the cookie database aside (recommended, reversible)

1. Fully quit DSH and confirm both the tray process and any background process are gone.
2. Open the Network directory and rename Cookies and Cookies-journal, for example with a .bak suffix.
3. Start DSH again; the app recreates a fresh cookie database.
4. Once the main window opens, decide whether to keep the backup. If startup still fails, rename the files back to roll back.

This clears cookies for every site embedded in the desktop client, but it does not touch DSH data: sessions, plugins, and credentials are not stored there.

Option 2: Delete only dsh-auth-* rows (keep other cookies)

1. Quit DSH and copy the Cookies file as a backup.
2. Open it with SQLite and run:

DELETE FROM cookies
WHERE host_key LIKE '%127.0.0.1%'
  AND name LIKE 'dsh-auth-%';

3. Close the database and start DSH again.
4. If startup succeeds, watch the next restart: a new row is expected, which means the mechanism is still there and only the counter was reset.

Do not edit the database while the app is running. SQLite WAL and the in-memory cache can write the old rows back on exit, which looks like "I deleted them but nothing changed".

Option 3: Raise the header limit temporarily (data rescue only)

1. Quit DSH.
2. Set NODE_OPTIONS=--max-http-header-size=131072 in the launch environment.
3. Start DSH; 71 cookies are now accepted, so export the sessions or files you need.
4. Afterward, still clean up with option 1 or 2. Do not keep running with this variable.

This only raises the ceiling. Cookies keep accumulating, and the same failure returns at the new ceiling.

DSH Plugin: Prevention: wait for the official fix, or patch it yourself

As of the community re-check, the official build is still unfixed: rc.2, rc.3, and rc.4 share the same naming and write logic in browser-auth.ts, while the community patch was verified to start normally on rc.4.

If you do not want to clean manually every time, there are three directions:

1. Clear same-family cookies at startup: call session.clearStorageData({ storages: ["cookies"] }) during Electron carrier startup. The community used this in another carrier that attaches a runtime on a random port and it ran for weeks; the cost is clearing all cookies.
2. Drop the port from the cookie name: hash the authority without the port so multiple launches on one machine reuse one name, overwriting the value instead of adding a row.
3. Clean up selectively at startup: keep backward compatibility, but delete rows that are same-domain, start with dsh-auth-, and do not match the current name. This touches only your own cookies.

One more change is easy to overlook: include the HTTP status code when connectDesktopWelcome throws. Right now 401 and 431 share the same Web authentication failed sentence, leaving users to guess. Exposing the status code at least separates a credential problem from a header problem immediately (#11408).

DeepSeek Harness: Things not to do

The following moves either worsen the failure or hide the real cause; avoid them before attempting a fix.

1. Do not reinstall to "fix" this. The cookie database lives in userData, and uninstalling usually leaves it behind, so the counter survives and the reinstall looks useless.
2. Do not delete cookie files while DSH is running. Fully quit first; otherwise WAL may write the old rows back.
3. Do not treat NODE_OPTIONS as a long-term fix. It raises the ceiling but does not stop accumulation.
4. Do not run the desktop app and dsh web against the same DSH_HOME. Both instances mint cookies, doubling the accumulation rate and amplifying other concurrent-write problems.
5. Back up before cleaning. The Cookies file and the whole Network directory are small; copy them first so you can roll back.

If you just need the app to open, option 1 is the fastest path. If you want to know whether you are in this family at all, count the cookies first and then check the log for 431. Once those two pieces of evidence line up, stop spending time on accounts and API keys.See dsh web authentication required: how to fix the prompt for the related case.