DeepSeek Harness transport failed: Image Tool Result (DSH)
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:
- 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.
- 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.
- Check the trigger point. Expected: the failure always appears right after a tool call that returned an image; here it was
cad_renderfromdsh-cad-design@0.2.0. - 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. - Check whether the message is verbatim identical. Expected: it is the same
DeepSeek Messages transport failedeach time, with no HTTP status or gateway detail attached. A real network failure usually leaves a status code or connection details incause, 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:
-
The wrapping site is
packages/llm/llm-deepseek/src/adapter.ts:80. Any exception thrown inside the request generator that is not anLlmErrorbecomesLlmError('DeepSeek Messages transport failed', 'TRANSPORT'). The originalErrorusually stays oncause— which is why "read that error's cause in the host log" is the first step. -
The throwing site is
prepareImagesatpackages/llm/llm-deepseek/src/images.ts:41-62. It walks every user message and tool message and, for each image reference, callsattachments.readImageRequest(...)at:55. A missing or unreadable attachment throws an ordinary Error, which the layer above turns intoTRANSPORT.
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:
-
Find that
TRANSPORTin the host log and read itscause. Expected: thecauseis 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. -
Check whether the
attachmentIdin the image block really exists. In this case the structure was:
{"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.
-
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 asimage/png. A length mismatch or a decode failure means corrupt content or a wrong media type. -
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:
- Do not hand-assemble
{"type":"image","attachment":{...}}in a tool result. The shape looks right but nothing was persisted, soprepareImageswill certainly fail to read it. - Call the attachment service to write the bytes first, obtain the real
attachmentId,bytes,mediaTypeand dimensions, and only then assemble the result block. - Self-check before returning: call the read interface once with the same
attachmentId, confirm it reads back and the length matches the declaration. - Throw structured errors rather than a bare
Error. Otherwise the adapter wraps it asTRANSPORT, disguising "my image was not stored properly" as "the user's network is broken". - 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.
- 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:
- Continue working in a new session. Expected: as long as the same image tool is not triggered, conversation and model calls are normal.
- Identify the plugin. Look back at the last successful tool call before the breakage; here it was
cad_renderfromdsh-cad-design. Disable or upgrade that plugin and try the same kind of call again. - 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.
- 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. - Include three things when reporting: the
causeof theTRANSPORT, theattachmentId, 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:
| Signal | Real network failure | Local error wrapped |
|---|---|---|
| Elapsed time | Connection or timeout cost, usually several hundred ms or more | About 0ms |
| Reproduction scope | Any session, any request may fail | Only that specific session; new sessions fine |
| Trigger | Network jitter, proxy, DNS, rate limiting | Right after a tool result that carried an image |
| cause | Network stack error, timeout, connection reset | Attachment read/decode error, ordinary Error |
| Retry outcome | May recover when intermittent | Fails 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:
- 0ms basically equals "never sent"; suspect the local preparation stage first.
causeis the original error; do not stop at the outertransport failed.- Every turn failing + new session fine = a bad block in history, not a provider problem.
- The
attachmentIdmust be lookable-up; if it is not, the plugin skipped the attachment API. - Retrying does not help this class of error, so do not spend time pressing send again.
- Plugin authors should proactively avoid a bare
Error, or the next user will be misled by this same sentence.
Source: Discussion #11658.
FAQ
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.
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.
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.
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
- #11658 — a cad_render image makes the session report TRANSPORT permanently· deepseek-ai (GitHub Discussions)