DeepSeek Harness plugin errors: loading, PENDING, execute

Most DeepSeek Harness (DSH) plugin errors during development share one trait: they do not throw — they fail silently. Mixing export forms means the plugin is never recognized, a missing inject leaves it in PENDING, returning prose from execute means Code Mode gets no fields, and one file read inside a card presenter crashes session replay. None of these are syntax errors, and your compiler will not warn you. This article organizes the frequent ones as symptom, cause, and fix. Every DSH plugin hits the same set of silent-failure traps.

DSH plugin error quick reference

Find the symptom you can see, then jump to its section. (Based on the official Your first plugin and Tool authoring reference pages.)

DSH plugin loading and state errors

A plugin with no logs, stuck in PENDING, or moved to FAILED is failing at load time — check the export form, the inject declaration, and what apply does as a side effect.

Error 1: the plugin never enters the state machine

Symptom: the config tree has an entry, but the plugin logs nothing and has no Fiber state.

Cause: the framework reads your module as exactly one form. Function form uses named exports; object and class forms use a default export (source):

// Function form: named exports.
export const name = 'my-plugin'
export function apply(ctx: Context) { /* ... */ }

// Object form: default export.
export default { name: 'my-plugin', inject: ['tools'], apply(ctx) { /* ... */ } }

The most common mix-up is writing both export default and a named apply — the framework reads the default export and silently ignores the other apply, and vice versa.

Fix: keep exactly one form per module, with name, inject, and apply in the same export. Full form selection is covered in DSH plugin development spec.

Error 2: a DSH plugin stuck in PENDING

Symptom: the plugin sits in PENDING and none of the code inside apply ever runs.

Cause: PENDING means the plugin is declared but its required services are not ready. A plugin that declares inject waits for every required service before apply runs, so an injected name that does not exist means it waits forever (source).

The second, sneakier cause is writing a hard dependency as an optional lookup:

// Wrong: a hard dependency as an optional lookup; the plugin reaches ACTIVE half-broken.
export function apply(ctx: Context) {
  const tools = ctx.get('tools')
  tools?.register(/* ... */)
}

// Right: declare it in inject, and the plugin simply does not load without it.
export const inject = ['tools']
export function apply(ctx: Context) {
  ctx.tools.register(/* ... */)
}

Fix: ask whether the plugin "cannot work without the service" or "does one extra thing when it is there" — the first goes into inject, only the second uses ctx.get(). For a plugin that installs but never activates, see plugin not activating.

Error 3: a DSH plugin's state moves to FAILED

Symptom: the Fiber state becomes FAILED and the startup log carries a stack trace.

Cause: a synchronous throw inside apply fails the load. Three patterns cause most of them:

1. Blocking work inside apply: apply is the synchronous initialization phase; network requests and large file reads belong in a background job.
2. Ordering assumptions: inject guarantees services are ready, not that your callbacks run in the order you imagine.
3. One-shot global side effects: when a dependency disappears the plugin is automatically unloaded and reloaded when it returns, so apply runs again (source).

Fix: keep apply light and repeatable. If it still throws, confirm with local debugging and --dump-config that the code actually mounted is the code you edited.

DSH plugin contract and rendering errors

Tool and card mistakes never throw — they only make fields unavailable or replay crash. The contract lives in what execute returns; rendering lives in presenter purity.

Error 4: breaking the execute contract

Symptom: the tool shows output in the UI, but in Code Mode await tools.xxx() yields a string and no ids or fields.

Cause: execute must return exactly one canonical JSON value. The registry snapshots that value as lossless JSON, validates it, freezes it, and passes it to output.render(args, value) for model-facing content. Returning content blocks from the body, or making callers parse prose, breaks the contract (source).

// Wrong: model-facing prose used as the return value.
async execute(args) {
  return [{ type: 'text', text: `wrote ${args.path}` }]
}

// Right: return a structured canonical value and leave prose to render.
output: {
  schema: { type: 'object', properties: { path: { type: 'string' }, bytes: { type: 'number' } } },
  render: (args, value) => [{ type: 'text', text: `wrote ${value.path} (${value.bytes} bytes)` }],
},
async execute(args) {
  const bytes = await write(args.path)
  return { path: args.path, bytes }
}

Four more hard rules live in the same section — check them all before publishing:

• A throw means isError: throw for infrastructure failures; represent a non-ideal but successful domain outcome inside the canonical value (the same applies to a whitelisted card render intent).
• Honor exec.signal: cancel in-flight work when it fires.
• Do not mutate the definition after registration: registration borrows your readonly definition, so do not change its schema or replace callbacks; to hot-swap, dispose the owning effect and register the replacement.
• Args are validated, readonly input: defineTool validates model-generated arguments against the schema first, so execute receives inferred types; only constraints the DSL cannot express (non-empty strings, positive numbers, cross-field rules) are yours to check by hand.

The full tool-side walkthrough is in how to write a tool plugin.

Error 5: impure DSH plugin card presenters

Symptom: live runs look fine, but replaying a session crashes the card or shows content that does not match what happened.

Cause: presentCall / presentResult run on live streaming and on session-log replay, so they must be pure functions of args plus the result: no I/O, no reading session state, no clock or random. Reading a file's previous content or the working directory inside presentCall crosses that line (source).

The sibling mistake: leaking UI-only formatting into the model result. Fenced console blocks, inline diffs, and relativized paths do not belong in the canonical value or the model-facing content merely to serve a UI. output.render owns model prose; presentationMeta plus the presenters own replayable card state.

Fix: when a card needs result-time facts (applied hunks, for instance), derive replayable JSON from the same canonical value with output.presentationMeta(args, value) and hand it to presentResult — never read the filesystem for a card. One built-in cushion: defineTool only soft-validates the display path, so malformed or older logged arguments make the presenter return undefined and fall back to a generic card instead of throwing, which keeps replay from crashing.

DSH plugin distribution and install errors

Exit code 0 on install does not mean the plugin works: the config layer may never reach the profile, and the build output may never be in the package.

Error 6: installed but never mounted

Symptom: installation succeeds with exit code 0, yet the config tree has no plugin entry.

Cause: a distributed plugin ships as a bundle: package.json points dsh.bundle.patch at cordis.patch.yml, and that config layer is what inserts the plugin entry into the tree. Ship only index.js, or leave cordis.patch.yml out of files, and installers never receive the config layer.

{
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

Fix: verify files includes the patch before publishing, then confirm the entry landed with dsh --profile demo --dump-config. A related trap: patches replace whole lines rather than deep-merging, so write the entire line whenever you override a field. The packaging flow is in packaging a bundle.

Error 7: the host crashes right after installing a DSH plugin

Symptom: install from github:owner/repo finishes without errors, then the host exits with ERR_MODULE_NOT_FOUND on restart.

Cause: a git distribution pulls source and does not run a build. If the repository ignores lib/ while main points at lib/index.js, the installed package has source but no entry artifact. Nothing surfaces at install time — checking the install command's exit code is nowhere near enough.

Fix: in order of preference — (1) publish to npm, where the tarball carries build output and installers need no build permission; (2) have the author add a prepare script and let users opt in through allowBuilds in the profile; (3) distribute a pnpm pack tarball meanwhile. The full comparison is in publishing to npm.

DSH plugin resource cleanup errors

Unloading is not stopping: resources created outside ctx must be handed back to the framework by you.

Error 8: resources that outlive unload

Symptom: after the plugin unloads, its timer keeps logging or its connection stays open.

Cause: anything registered through ctx is tracked and revoked on unload — ctx.on, ctx.tools.register, ctx.llm.registerAdapter, and ctx.effect are all covered, so you never hand-write removeListener or clearInterval (source). What leaks is resources created outside ctx: network connections, file handles, and your own setInterval timers.

Fix: wrap those in ctx.effect() and return a disposer.

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('heartbeat'), 5000)
    return () => clearInterval(timer)   // Runs when the plugin unloads.
  })
}

One detail worth memorizing: disposers start in reverse registration order, but multiple async disposers run concurrently and are not guaranteed to finish one by one. Cleanup with ordering dependencies (close the stream, then the connection) must live inside a single ctx.effect(), because splitting it removes the guarantee.

Catching DSH plugin errors before publishing

Only error 3 hands you a stack trace; the other seven fail silently — so "it installed" is never an acceptance criterion. The minimum pre-release routine:

1. Run dsh --profile demo --dump-config and confirm your entry is in the config tree (catches error 6).
2. add the plugin into a clean profile, restart the host, confirm it does not crash (catches error 7).
3. Unload it once and check that logs and connections actually stop (catches error 8).
4. Call the tool from Code Mode once and confirm you get structured fields (catches error 4).

For the rule-by-rule checklist see DSH plugin development spec; for debugging channels and config layering see local debugging; for silent config fallbacks see how to define plugin config. To compare against real plugin layouts and bundle declarations, browse DSH Plugin Hub.