ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness transport failed: Image Tool Result (DSH)

TroubleshootingPublished 2026-11-03Author: DeepSeek Plugin Market
DeepSeek HarnessTRANSPORTtransport failedattachmentimage tool resultprepareImages
After one tool returns an image, DeepSeek Harness fails every turn with DeepSeek Messages transport failed in 0ms: an ordinary Error is wrapped as TRANSPORT.

In DeepSeek Harness (DSH), the error most easily blamed on the network is DeepSeek Messages transport failed (TRANSPORT). Sometimes it is a real transport failure, but another common case is this: one tool call returned a result block containing an image, and from then on every turn of that session fails with the same message, in about 0ms, while the network is perfectly fine. The reason is that adapter.ts:80 wraps any ordinary Error that is not an LlmError thrown inside the request generator as LlmError('DeepSeek Messages transport failed', 'TRANSPORT') — while the thing actually throwing is prepareImages failing to read an image attachment. The test is blunt: 0ms + every turn + a new session is fine = local wrapping, not the network (#11658).

Zero milliseconds is the test: a real network failure does not return instantly

In one sentence: failing in about 0 milliseconds means the request never left, so the problem lies in the local preparation stage before sending. Split the test into five parts:

  1. Check the elapsed time. Expected: the error returns in about 0ms. A real network failure either waits for a connection timeout or goes through a retry cycle; it does not end instantly.
  2. Check the reproduction scope. Expected: the same session fails every turn, while a new session that does not call that tool works perfectly. That alone rules out the provider, the account and the network.
  3. Check the trigger point. Expected: the failure always appears right after a tool call that returned an image; here it was cad_render from dsh-cad-design@0.2.0.
  4. Check whether retrying helps. Expected: the default retry policy allows 5 retries for TRANSPORT, yet retries do nothing here — the failing point is the same local attachment every turn and it cannot heal itself.
  5. Check whether the message is verbatim identical. Expected: it is the same DeepSeek Messages transport failed each time, with no HTTP status or gateway detail attached. A real network failure usually leaves a status code or connection details in cause, so a word-for-word identical wrapper points back to one single local exception.

Once all five hold, stop checking DNS, proxies and API keys; turn your attention to "what exactly is inside that image result".

The mechanism: a catch-all rewrites a local error as a network error

In one sentence: the adapter's catch-all exists to unify error types, and the price is losing the original meaning so that a local attachment problem masquerades as a transport failure. Two implementation sites:

  1. The wrapping site is packages/llm/llm-deepseek/src/adapter.ts:80. Any exception thrown inside the request generator that is not an LlmError becomes LlmError('DeepSeek Messages transport failed', 'TRANSPORT'). The original Error usually stays on cause — which is why "read that error's cause in the host log" is the first step.

  2. The throwing site is prepareImages at packages/llm/llm-deepseek/src/images.ts:41-62. It walks every user message and tool message and, for each image reference, calls attachments.readImageRequest(...) at :55. A missing or unreadable attachment throws an ordinary Error, which the layer above turns into TRANSPORT.

Why "permanent" rather than "occasional": that bad block stays in session history. Every following turn rebuilds the request, so prepareImages reads the same attachment again and fails again. Unless you remove the bad block from history or switch sessions, it will never fix itself.

This also explains why the message points at the network: the wrapper keeps only the error code and never promotes cause to a user-visible place, so everyone's first reaction is "the network dropped".

Three evidence steps: the cause, whether the attachment exists, whether the bytes decode

The decisive signal is that cause shows an attachment read failure, and the attachmentId points at a record that is missing or unreadable. In order:

  1. Find that TRANSPORT in the host log and read its cause. Expected: the cause is not a network stack error but something attachment-read related (record not found, read failed, decode failed). This single step separates a real network failure from local wrapping.

  2. Check whether the attachmentId in the image block really exists. In this case the structure was:

json
{"type":"image","attachment":{"attachmentId":"sha256:ce7f7d98…","mediaType":"image/png","bytes":9466,"width":472,"height":472,"name":"cad-preview.png"}}

Expected: look up sha256:ce7f7d98… in attachment storage. If there is no record, the plugin hand-assembled a structure with an id instead of registering the bytes with the attachment service.

  1. If the record exists but reading fails, verify the bytes. Expected: fetch the attachment, check whether the byte length matches the declared bytes, and whether it decodes as image/png. A length mismatch or a decode failure means corrupt content or a wrong media type.

  2. Confirm against a healthy session. Create a new session, do not call cad_render, and expect normal conversation. Then return to the original session and send an ordinary message; expect it still fails in 0ms. Those two comparisons nail down "the bad block is in history".

The right way on the plugin side: persist first, then return the block

In one sentence: the attachmentId in an image result must come from a real attachment API registration, because the harness cannot manufacture bytes from an id. The thread's conclusion is direct: if step 2 finds no attachment, the plugin has to store the image through the attachment API before returning the result block.

A checklist for plugin authors:

  1. Do not hand-assemble {"type":"image","attachment":{...}} in a tool result. The shape looks right but nothing was persisted, so prepareImages will certainly fail to read it.
  2. Call the attachment service to write the bytes first, obtain the real attachmentId, bytes, mediaType and dimensions, and only then assemble the result block.
  3. Self-check before returning: call the read interface once with the same attachmentId, confirm it reads back and the length matches the declaration.
  4. Throw structured errors rather than a bare Error. Otherwise the adapter wraps it as TRANSPORT, disguising "my image was not stored properly" as "the user's network is broken".
  5. Regression-test this path when upgrading. Image results are a high-risk return value: a single failure makes the whole session unusable, so the testing cost is far higher than for ordinary text blocks.
  6. Consider self-describing fields on the result block, such as render width, source tool and generation time, so a user facing an unusable session can tell which call produced the block instead of only seeing a sha256: prefix.

Scope note: this constraint is an agreement between plugin and harness, not a DSH configuration option. Users will not find a "repair image attachment" switch in the UI, and should not look for one — the fix can only come from the plugin side changing how it returns results.

User-side emergency response: switch sessions instead of arguing with a broken one

In one sentence: the bad block is already in history and the current session cannot be rescued by retrying; the practical move is to open a new session and upgrade or replace the plugin at fault. Steps:

  1. Continue working in a new session. Expected: as long as the same image tool is not triggered, conversation and model calls are normal.
  2. Identify the plugin. Look back at the last successful tool call before the breakage; here it was cad_render from dsh-cad-design. Disable or upgrade that plugin and try the same kind of call again.
  3. If you must keep the original session, remove the tool result with the bad attachment. That is session-file surgery: back up before editing, or give up on the session, which costs less.
  4. Do not keep pressing retry. The default retry policy allows 5 retries for TRANSPORT, but every turn fails in the same place, so retrying only repeats the same path.
  5. Include three things when reporting: the cause of the TRANSPORT, the attachmentId, and whether that record exists in attachment storage. Those three let the author pinpoint it in one pass instead of guessing back and forth.

One table to separate "real network failure" from "local wrapping"

In one sentence: elapsed time, reproduction scope and cause together distinguish the two kinds of TRANSPORT, with no packet capture needed. The comparison:

SignalReal network failureLocal error wrapped
Elapsed timeConnection or timeout cost, usually several hundred ms or moreAbout 0ms
Reproduction scopeAny session, any request may failOnly that specific session; new sessions fine
TriggerNetwork jitter, proxy, DNS, rate limitingRight after a tool result that carried an image
causeNetwork stack error, timeout, connection resetAttachment read/decode error, ordinary Error
Retry outcomeMay recover when intermittentFails every turn; retrying is useless

Paste this table into your investigation notes; spending ten seconds comparing against it the next time you see TRANSPORT saves most of the wasted attempts.

Debugging notes

The big trap with the TRANSPORT code is that its name sounds so much like the network, so the rule is to check elapsed time and reproduction scope first. Six points:

  1. 0ms basically equals "never sent"; suspect the local preparation stage first.
  2. cause is the original error; do not stop at the outer transport failed.
  3. Every turn failing + new session fine = a bad block in history, not a provider problem.
  4. The attachmentId must be lookable-up; if it is not, the plugin skipped the attachment API.
  5. Retrying does not help this class of error, so do not spend time pressing send again.
  6. Plugin authors should proactively avoid a bare Error, or the next user will be misled by this same sentence.

Source: Discussion #11658.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

DeepSeek Harness fails every turn after an image: why?

In DeepSeek Harness it is usually not a network failure but a local error wrapped as TRANSPORT by the adapter's catch-all. adapter.ts wraps any ordinary non-LlmError thrown inside the request generator as LlmError('DeepSeek Messages transport failed', 'TRANSPORT'); what actually throws is most often prepareImages failing to read the image attachment.

Real network TRANSPORT vs wrapped error in DeepSeek Harness?

In DeepSeek Harness, look at the elapsed time: failing in about 0ms means the request never left, so it is a wrapped local error, whereas a real network failure waits for a connection timeout or a retry cycle. Then check whether it fails every turn — the bad block stays in session history, so every rebuilt request re-parses the same attachment and fails again, while a new session that never calls that tool works fine.

Is the attachmentId in DeepSeek Harness image blocks real?

In DeepSeek Harness attachment storage, look up the record for that sha256 id and compare its byte count with the declared bytes. If it is not there, the plugin hand-assembled an image block without persisting the bytes through the attachment API; if it exists but cannot be read, check whether the bytes decode as the declared image/png to rule out corrupt content or a wrong media type.

How should plugins return images to DeepSeek Harness?

For DeepSeek Harness, persist the image bytes through the attachment API first, get the real attachmentId, and only then return a result block containing an image. Do not just assemble a JSON structure with an attachmentId. The harness cannot conjure bytes from an id, so prepareImages fails every time it re-reads the attachment.

Related Terms

TRANSPORT
TRANSPORT is the error code DeepSeek Harness uses for a transport-layer failure when calling the model, with the message DeepSeek Messages transport failed. It can come from a genuine network exception, but the adapter may also use a catch-all to wrap any local ordinary Error, so the code alone does not tell you the cause.— https://github.com/deepseek-ai/deepseek-harness/discussions/11658
prepareImages
prepareImages is the function in the llm-deepseek package that processes images before building a request, around lines 41-62 of packages/llm/llm-deepseek/src/images.ts. It walks every user and tool message and calls attachments.readImageRequest for each image reference, throwing an ordinary Error when the read fails.— https://github.com/deepseek-ai/deepseek-harness/discussions/11658
LlmError
LlmError is the structured error type defined by the DeepSeek Harness model adapter layer, carrying an error code so callers can retry or report by type. Anything that is not an LlmError gets uniformly wrapped by the adapter, which is precisely why a local attachment read error is displayed as TRANSPORT.— https://github.com/deepseek-ai/deepseek-harness/discussions/11658

Sources