DeepSeek Harness Route 404: webserver disposer (DSH plugin)
After a DeepSeek Harness (DSH) plugin is unloaded or hot-reloaded, its HTTP routes start returning 404 and its WebSocket upgrade routes turn into "connect, then 0 bytes, immediately closed", while the log says nothing** — the classic root cause behind this kind of silent disappearance is that the webserver route disposer deletes by path without checking ownership.** The cleanup function returned by register() / registerUpgrade() is written as table.delete(route.path): if the same path is first registered by A, and A's disposer only runs after B has registered, B's route is silently deleted and A's disposer reports no error at all. Both functions throw duplicate ... route on a repeat registration, which shows path is already a unique key — and precisely because it is unique, a disposer should confirm it is deleting its own entry (#11579).
Symptoms: a silent 404 and a 0-byte disconnect, with no trace in the log
In one sentence: this is not "the plugin did not start" but "the route was deleted by someone else's cleanup function" — the first leaves load logs, the second leaves nothing at all. Three manifestations to compare:
- HTTP routes: requests return 404, with no log beyond "route not found". It looks exactly as if that path had never been registered.
- Upgrade routes: the handshake disconnects with 0 bytes, indistinguishable from "the path does not exist", and the client gets no error code.
- The most confusing variant: the plugin really has been unloaded and no longer works, yet some
/statusstill returns 200 — that is another issue (the HTTP route's disposer was never collected byctx.effect, so unload did not delete it), not the "deleted someone else's" problem in this article.
The reporter's own experience in the thread: the plugin registered 1 upgrade route plus 2 HTTP routes; after unload /status still returned 200, /send-image returned 503, and /pet (upgrade) gave 0 bytes. Behind those three symptoms sit two different mechanisms, and triage must attribute them separately.
Minimal reproduction: four steps that expose the cross-deletion
The decisive signal: register A, unregister, register B, then call A's disposer once more — and B disappears. Steps:
- Create a WebServer instance and register A. Run
const w = new WebServer()andconst disposeA = w.registerUpgrade({ path: '/pet', tag: 'A' }). - Invoke A's disposer once, simulating A going offline. Run
disposeA(); expect/petto vanish from the upgrades table. This is normal cleanup. - Register B, simulating a new instance coming up. Run
w.registerUpgrade({ path: '/pet', tag: 'B' }); expect noduplicate upgrade route, since A already unregistered. - Call A's disposer again.
disposeA()
console.log(w.upgrades.has('/pet')) // false — B was deleted
Expected: it prints false, and B's route disappears without a sound. register() behaves identically when going through the exact / prefixes tables (#11579).
The reproduction rests on one precondition: the disposer gets called a second time. That sounds contrived, but it is not — it happens whenever ctx.effect cleanup coexists with an explicit dispose().
Why it bites in real scenarios: the cleanup order is not under control
In one sentence: the order in which plugins unload and reload, and the order in which multiple instances register the same service, are all outside anyone's control, so as long as "an old disposer runs after a new registration", the route disappears. Three uncontrolled factors:
- Disposers collected by
ctx.effectrun when the plugin unloads, but the plugin does not decide when that unload happens. - An explicit
dispose()may be called as well, so the same cleanup function runs twice; the first time is normal, the second deletes the later arrival. - Multi-instance scenarios (hot reload, two instances, plugin A replaced by a new version) make "the same path belonging to different instances in sequence" the normal case.
Both the reporter and the responder stress that this bug is expensive to chase not because the symptom is complex, but because there is no log and no exception — you can see "the route is gone" and never "who deleted it".
The correct implementation: confirm ownership before deleting
In one sentence: change the disposer to if (table.get(route.path) === route) table.delete(route.path), one site per table, and that is the minimal change. Steps:
- Change the disposer in
register(). Replace() => { table.delete(route.path) }with an ownership check:
return () => {
if (table.get(route.path) === route) table.delete(route.path)
}
- Change the disposer in
registerUpgrade(). Add the same ownership check, targetingthis.upgrades. - Confirm
routeis an object reference. The registration stores the object itself, soget(path) === routeis an O(1) reference comparison with no performance cost. - Run four assertions. Expected: a second registration of the same name throws
duplicate; an old disposer really does delete a later-registered upgrade route;register()'s exact table is hit the same way; and after the change the cross-deletion stops. - Add this regression to the plugin's own tests. It is an API contract behavior; reading the code easily misses it, so it must be locked with assertions.
An alternative design is to give the disposer an ownership token (wrapping
{ route, token }internally), but the minimal change above is already sufficient and there is no need to reshape the data structure for it.
When it finds "not mine": skip silently with a warn, never throw
In one sentence: throwing is not dangerous by itself, but disposers in the same ctx.effect are chained with .then and have no try/catch, so one throw stops every later one from running and causes a leak. The evidence comes from comparing three approaches:
| Behavior when the route is not its own | Result |
|---|---|
Throw, several routes sharing one ctx.effect | Everything after is skipped; leak |
Throw, one ctx.effect per route | No leak (each .then chain is independent) |
Skip silently (if (get === route) delete) | No leak |
The root of it is cordis/lib/index.js:1179: a batch of disposers is chained with task = task.then(() => runDisposable(disposable)), with no try/catch. By contrast, fiber._unload() (:1373-1382) wraps each one in its own try/catch, so a throw there only hurts itself.
Two reasons for the decision:
- A disposer being called twice is a legitimate scenario, not a caller bug; throwing on a legitimate scenario makes no sense.
- The cost of a leak exceeds the value of exposing the bug: a leak looks like "the route is still there, the plugin is already dead", and that illusion cost the reporter 10 hours.
If you really want a trace, use logger.warn to log one line — "disposer found the path now owned by another route" — which neither interrupts anything nor hides the evidence.
User-side triage order: first separate "never registered" from "was deleted"
In one sentence: work through three layers — route table, plugin load state, cleanup order — to avoid collapsing two distinct bugs into one. Steps:
- Confirm whether the plugin is currently loaded. Expected: a healthy status in the plugin list and no load failure. If the plugin never came up, read its load logs first and do not suspect routes.
- Request the route directly and read the status code. HTTP 404 = the route is not in the table; an upgrade 0-byte disconnect = likewise not in the table. Both point at "the registration is gone".
- Recall the order of operations. Expected: did the failure appear right after "unload or reload, then install a new version"? If so, this article is a strong candidate.
- Check whether the plugin collected its disposer into
ctx.effect. If it did not, the route survives unload and keeps returning 200 — that is "never deleted", not "deleted the wrong one", the opposite direction. - Record the version and line numbers. The responder cross-checked
packages/host/webserver/src/index.ts:445-466(isomorphic withlib/index.js:326-346in rc.2), with the disposers at:451and:465.
Fix status and boundaries
In one sentence: this is a defect at the API contract layer, fixable in one line on the product side, but as of that discussion it has not been merged; users and plugin authors should both work around it with the ownership check. Three boundaries:
- Version consistency: master
ce7073d5atsrc/index.ts:445-466behaves the same as0.2.1-rc.2atlib/index.js:326-346, so switching versions does not change the conclusion. - Submission channel: the repository's
CONTRIBUTING.mdstates that external PRs are not currently accepted and issues go to GitHub Discussions, which also means the fix pace depends on the maintainers. - Not the only cause: a 404 after a hot reload can also come from "the plugin did not reload" or "the disposer was never collected by the effect". This article covers only the missing-ownership-check branch; the other two need their own evidence.
Debugging notes
The rule for route failures is: first establish whether the route is in the table, then discuss why it is not. Six points:
- A silent 404 should point at cleanup logic first, not at the plugin's registration code.
- An upgrade's 0 bytes are equivalent to a 404; do not go capture handshake packets looking for a reason.
- Distinguish "never deleted" from "deleted the wrong one": the first leaves the route responding, the second makes it vanish.
- A disposer must be idempotent; being called twice is not an exceptional scenario.
- Multiple disposers in one effect need per-item try/catch, otherwise one throw drags down the whole batch.
- Plugin authors should encode the ownership check as a test; it is a contract, not something to rely on memory for.
Source: Discussion #11579.
FAQ
In DeepSeek Harness the common cause is a route disposer that deletes by path without checking ownership. When the old instance's cleanup runs after the new instance registers, it removes the new instance's route of the same name, entirely silently, and the only visible effect is a 404 at request time. The code is in the cleanup function returned by webserver's register() / registerUpgrade().
In DeepSeek Harness, once the upgrade route is removed, the server treats that path as nonexistent, so it tears down during the handshake without sending any data. That behaves exactly like 'the path does not exist', so from the client side there are only 0 bytes — no 404, no exception log — which is what makes this failure hard to find.
In a DeepSeek Harness plugin, compare ownership before deleting: if (table.get(route.path) === route) table.delete(route.path). One site for each of register's exact/prefixes tables and one for registerUpgrade's upgrades table. route is an object reference and the comparison is O(1), so there is no performance cost.
Because in DeepSeek Harness the disposers in the same ctx.effect are chained with .then and no try/catch (cordis/lib/index.js:1179). One throw means the later ones are never called at all, causing route leaks. A disposer being invoked twice is a legitimate scenario, so silently skipping with a logger.warn is the safer behavior.
Related Terms
- disposer
- A disposer is the cleanup function returned when DeepSeek Harness registers a resource; calling it should undo that registration. Both register() and registerUpgrade() on the webserver return a disposer, and plugins usually hand them to the framework through ctx.effect() so they run on unload.— https://github.com/deepseek-ai/deepseek-harness/discussions/11579
- registerUpgrade
- registerUpgrade is the webserver interface for registering a WebSocket upgrade route, storing it in the upgrades table by path; registering the same path twice throws duplicate upgrade route. Its disposer lives around packages/host/webserver/src/index.ts:465 and likewise only does table.delete(route.path).— https://github.com/deepseek-ai/deepseek-harness/discussions/11579
- ctx.effect
- ctx.effect is the lifecycle registration mechanism on the DeepSeek Harness plugin context: the callback you pass returns a disposer that runs when the plugin unloads. It can coexist with an explicit dispose(), which is why calling the same disposer twice is a legitimate scenario.— https://github.com/deepseek-ai/deepseek-harness/discussions/11579