ChatGPTClaudeGrok / X / CursorGemini

DSH plugin reference errors: seven codes, three owners

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referenceerror codesretry
One failure toast for seven causes teaches users nothing. Group the codes by owner, decide what may retry, and keep budget-exceeded distinct from truncation.

Telling users only "reference failed" is the same as telling them nothing. DSH plugin's seven codes exist so hosts can split the paths: which failures are user mistakes, which are configuration problems, and which deserve a retry.

DeepSeek Harness: Why codes beat copy

Codes are the contract; messages are descriptions. Their stability is not comparable. (source) Scene:

text
catch (err) {
  toast('Reference failed'); // seven causes, one sentence
}

The problem is not rough wording but that "the user can fix this" and "there is nothing to do but wait" become the same experience.

DSH plugin exposes seven codes, and the host protocol maps them into its own error wrappers. That mapping is one-time work that makes every later branch testable.

Never write message.includes('budget'): copy changes, codes do not.

DeepSeek Harness: Seven codes in three groups

Seven failures fall into three groups, each with a different fixer. (source) Grouping:

GroupCodesWho acts
InputINVALID_CONFIG, INVALID_REFERENCE, SELF_REFERENCE, TOO_MANYHost or user
ReadREAD_FAILED, BUDGET_EXCEEDEDEnvironment or budget settings
LifecycleCANCELLEDNobody

Input failures are half the set, which means most problems can be caught before the call: bad config, malformed mention, self reference, too many references.

Read failures are the genuine runtime issues, and only READ_FAILED is worth an automatic retry.

Lifecycle is not a failure at all; this turn simply did not happen.

DeepSeek Harness: The four input-side failures

They share one trait: retrying the same input changes nothing. (source) One by one:

  1. INVALID_CONFIG — the integration is misconfigured. Check dependency injection and required fields; do not show this to end users, because it is a developer problem.
  2. INVALID_REFERENCE — the reference is malformed or invalid. Ask the user to choose again instead of resending it unchanged.
  3. SELF_REFERENCE — the current session was referenced. The product should disable that option up front rather than waiting for an error.
  4. TOO_MANY — the count limit was exceeded. Ask users to remove references, or cap selection in the UI.

The second is most common: a host builds dsh-session: strings itself and a bracket in the label breaks parsing. Using the candidate's mention prevents most of these.

The third follows "prevent when you can": filtering the current session out of the candidate list is better than an error message.

DeepSeek Harness: Read, budget, lifecycle

One may retry, one depends on budget, one must not retry. (source) Three entries:

  • READ_FAILED — the source log cannot be read. Retry once or twice with backoff; if it still fails, say the session is temporarily unreadable and keep the user's selection.
  • BUDGET_EXCEEDED — the budget was insufficient. Retrying is pointless unless the scope shrinks or the model has more capacity.
  • CANCELLED — the user navigated away or stopped. No notice, no retry, no empty context.

The difference between BUDGET_EXCEEDED and truncation must be explicit: truncation succeeds with less content and carries truncated plus omission facts; exceeding the budget fails with nothing to publish.

Treat them as one and you get "the UI said success and the model received nothing".

DeepSeek Harness: The retry matrix

One table decides what the button looks like. (source) Comparison:

CodeMust change before retryUI action
INVALID_CONFIGFix config and restartDo not show to end users
INVALID_REFERENCEChoose againReturn to selection
SELF_REFERENCEPick another sessionDisable the current session
TOO_MANYRemove referencesShow the limit
READ_FAILEDNothingOffer a retry button
BUDGET_EXCEEDEDNarrow scope or change modelOffer adjustment
CANCELLEDNothingStay silent

The middle column is a guardrail: retry without changing anything and you get the same code.

Logs should record that column too, not just the code; diagnosis then shows whether the caller followed the contract.

Mapping in the host

Enum to enum, never string to string. Use an exhaustive switch that sorts the seven codes into three handling classes: retryable, silent, and user-fixable. The default going to "user-fixable" is deliberately conservative so an unknown code never disappears silently.

One more: keep the original code and key counts in logs and telemetry. Redacting them to unknown removes the only clue during an incident.

DeepSeek Harness: Seven constructed failures

Seven cases confirm copy, logs, and buttons agree. (source) Steps:

  1. Pass invalid configuration and confirm INVALID_CONFIG with no user toast;
  2. Pass a hand-built broken reference and confirm INVALID_REFERENCE and a return to selection;
  3. Reference the current session and confirm SELF_REFERENCE (or that the UI already disabled it);
  4. Pass more references than the limit and confirm TOO_MANY;
  5. Break source storage or inject a read failure and confirm READ_FAILED with a working retry;
  6. Build an over-budget reference and confirm BUDGET_EXCEEDED, not truncation;
  7. Trigger the signal during prepare and confirm CANCELLED with no context published.

Each case asserts three things at once: the code, the UI copy, and the log fields. Disagreement means the mapping layer has a gap.

Cases 5 and 6 are the easiest to conflate; verify them separately instead of letting one case represent both failures.

With error routing done, cancellation timing deserves its own look. Read why DSH plugin cannot publish context after a cancel; for the budget and the 64 KiB fallback, read where the DSH plugin reference budget comes from; for the wider picture, read how DSH plugin implements session references.

Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can DSH plugin's SESSION_REFERENCE_READ_FAILED be retried automatically?

Yes, DSH plugin allows a limited retry. It means reading the source session failed, which may be transient; retry once or twice with backoff, then surface a user-visible notice.

Is BUDGET_EXCEEDED the same as truncation in DSH plugin?

No, DSH plugin treats truncation and budget failure differently. Truncation still returns usable content with omission facts, while exceeding the budget fails with nothing publishable. DSH plugin keeps them separate, and so should handling.

With DSH plugin, should a host add an empty context after SESSION_REFERENCE_CANCELLED?

No, DSH plugin publishes no context after cancellation. Cancellation means the call was abandoned. Filling in an empty context fakes a success that never happened.

Can a host parse DSH plugin error codes out of message text?

Do not parse DSH plugin codes out of message text. Codes are the stable contract while messages are human descriptions. Map code to your own error wrapper instead of matching copy bytes.

Related Terms

SESSION_REFERENCE_INVALID_CONFIG
The host integration configuration is invalid, such as missing dependencies or a malformed required setting.— DeepSeek Harness reference - Session references
SESSION_REFERENCE_INVALID_REFERENCE
The reference is malformed or invalid, so prepare cannot turn it into a readable source.— session-reference/src/types.ts
SESSION_REFERENCE_READ_FAILED
Reading the source session log failed; it may be transient and is one of the few codes suitable for retry.— DeepSeek Harness reference - Session references
SESSION_REFERENCE_CANCELLED
The call was cancelled, so no context is published even if underlying storage completes later.— DeepSeek Harness reference - Session references

Sources