Fixing UNKNOWN_TOOL and HTTP 400 Gateway Errors in dsh

UNKNOWN_TOOL, developer role rejected (HTTP 400), and tool calls that arrive with an empty name are almost always caused by dialect differences between how your OpenAI-compatible gateway implements the API and how DeepSeek Harness's adapter expects it to behave — not a bug in your prompt or your model choice. Isolate the cause by testing the same configuration against the official DeepSeek API first, then inspecting the effective config with --dump-config, then checking whether your gateway supports the specific role and streaming behaviors dsh relies on. This guide walks through that diagnosis path and the gateway-specific issues reported most often this week.

This is a companion to Use OpenAI, Anthropic, or Any OpenAI-Compatible API with DeepSeek Harness, which covers how to add a custom or OpenAI-compatible provider in the first place. This post picks up where that one leaves off: your provider is configured and DeepSeek Harness (dsh) can reach it, but tool calls start failing once you actually run an agent session.

Why this happens

"OpenAI-compatible" describes a wire format, not a guarantee of identical behavior. Gateways — self-hosted proxies, third-party aggregators, and domestic providers like Alibaba Cloud's Qwen/Bailian (DashScope) — each implement a subset of the OpenAI API surface, and the parts most likely to diverge are exactly the ones agent harnesses depend on most: which message roles are accepted, how streamed tool-call chunks are structured, and whether a tool's name field is repeated across continuation chunks or only sent once. dsh's llm-deepseek adapter was built against the OpenAI dialect as officially documented; a gateway that deviates even slightly in one of these areas produces errors that look like harness bugs but are really protocol mismatches.

Symptom checklist

Symptom	Likely root cause	Fix
`UNKNOWN_TOOL` error mid-session	Gateway returns a tool name in `tool_calls` that doesn't exactly match what dsh advertised in the request — truncated, re-encoded, or normalized differently	Non-streaming call first to confirm the exact name round-trips intact; if it doesn't, the gateway is mutating tool names and needs a fix on its side
`developer role rejected (HTTP 400)`	Gateway's OpenAI-compatible implementation doesn't accept the `developer` role that newer OpenAI-dialect message formats use in place of `system`	Check the gateway's own API docs for supported roles; dsh has no automatic downgrade path, so a gateway that only accepts `system` will keep rejecting these requests until it adds support
Tool call name comes back empty	Streamed `tool_calls` are split across multiple chunks, and the gateway only sends the `name` field on the first chunk instead of repeating it on continuations — reported in Discussion #3767	Community workaround: disable streaming for tool-call-heavy sessions where the gateway supports a non-streaming mode, or switch to a gateway/proxy known to preserve `name` across chunks

All three point back to the same root: OpenAI-compatible implementations differ in role support, streaming tool-call chunking semantics, and how tool names are transmitted. None of them are configuration mistakes you can fix purely from the dsh side — but you can usually confirm which one you're hitting in a few minutes.

Diagnosis path

Work through these in order rather than guessing at a fix:

Verify the configuration against the official DeepSeek API first. Point the same session at DeepSeek's own endpoint (or another known-good directory provider) with everything else unchanged. If tool calls succeed there, the problem is specific to your gateway's implementation, not your prompt, tools, or bundle setup.
Dump the effective configuration. Run:
```
dsh --profile web --dump-config
```
This prints the fully merged configuration tree — bundle defaults, your profile's cordis.patch.yml, $DSH_HOME/cordis.patch.yml, and any --patch overrides — so you can confirm the provider, base URL, and model entry dsh is actually using, rather than what you think you configured.
Check which API dialect the provider speaks. A custom provider declares api: openai-completions (or another supported wire format) in settings.yaml. Confirm your gateway actually implements chat completions rather than a Responses-style API or a partial subset — a mismatch here produces exactly the kind of malformed-request errors covered here.
Check role and streaming support directly against the gateway. Ask whether it accepts the developer role, and whether streamed tool_calls repeat the name field on every chunk or only the first one. Gateway vendor docs or a raw curl against the endpoint (bypassing dsh entirely) will usually answer this faster than trial and error inside a session.
Try toggling streaming, or hitting a different endpoint path, to isolate further. If the gateway offers both a streaming and non-streaming completion path, testing both narrows down whether the bug is in streaming chunking specifically or in the request itself.

Common configuration errors, revisited

Before assuming you've hit a gateway-dialect bug, rule out the more mundane configuration mistakes covered in Setting Up Your DeepSeek API Key and Models and Use OpenAI, Anthropic, or Any OpenAI-Compatible API with DeepSeek Harness:

MISSING_CREDENTIAL — the provider has no resolved key; set it in Settings → Models or via environment variable.
UNKNOWN_MODEL — the model ID isn't in any configured provider's model list; add it to the custom provider's models: entry, or use modelOverrides for a directory provider.
Attached images rejected before send — the model entry is missing input: [text, image] in settings.yaml; models default to text-only unless declared otherwise.

These produce distinct, clearly-labeled errors and are worth eliminating first — they're config mistakes on your end, not gateway-dialect issues, and the fix is a one-line YAML change rather than a workaround.

Domestic gateway case: Alibaba Cloud Qwen / Bailian (DashScope)

Community reports this week point to compatibility issues specifically with Alibaba Cloud's Qwen and Bailian (DashScope) OpenAI-compatible endpoints, surfacing as the UNKNOWN_TOOL and HTTP 400 role-rejection symptoms above. As of August 21, 2026 this is a community-reported pattern, not an officially confirmed root cause on either DeepSeek Harness's or Alibaba Cloud's side — later dsh or gateway releases may resolve it. If you're on one of these gateways, run the diagnosis path above before filing anything, since it's the fastest way to confirm whether you're hitting the same class of issue others have reported.

For a related but distinct problem — a gateway that's unreachable rather than incompatible — one Discussion thread (#3550) covers a user whose DeepSeek V4 Flash access through a domestic provider had no direct network path, and who worked around it by routing dsh through a local proxy via the community plugin dsh-llm-proxy. That's a network-reachability workaround, not a fix for the dialect issues above — worth knowing about, but don't reach for a proxy plugin if your actual symptom is UNKNOWN_TOOL with a gateway you can already connect to.

While debugging gateway configuration, you may also hit an unrelated but easily confused failure: dsh plugin add crashing with a JSON.parse error when a plugin's package.json starts with a byte-order mark (BOM), reported in Discussion #2798. That's an install-time parsing bug, not a gateway or model-provider issue — see Fixing DeepSeek Harness Plugin Install Errors if you hit it while installing a plugin during the same troubleshooting session.

When to report a bug

GitHub Issues are disabled on the deepseek-ai/deepseek-harness repository — the only feedback channel is GitHub Discussions. If you've worked through the diagnosis path above and still can't get tool calls working against your gateway, file a Discussion rather than an Issue, and include:

The full output of dsh --profile web --dump-config (redact API keys and any secrets).
The name of your gateway or provider (Qwen/Bailian, a specific proxy product, a self-hosted implementation, etc.).
Whether the same session succeeds against the official DeepSeek API or another directory provider.
Whether streaming was enabled, and whether disabling it changes the symptom.

That combination is usually enough for maintainers or other affected users to tell quickly whether you're hitting a known gateway-dialect gap or something new.

FAQ

Is UNKNOWN_TOOL a bug in DeepSeek Harness?

Not directly — it's almost always a mismatch between the tool name dsh sent and what the gateway returned in tool_calls, caused by how that specific gateway implements the OpenAI-compatible API. Confirm this by testing the same session against the official DeepSeek API; if it works there, the gateway is the variable.

Why does my gateway reject requests with "developer role rejected (HTTP 400)"?

Some OpenAI-compatible gateways only implement the older system role and haven't added support for the developer role that newer OpenAI-dialect message formats use. dsh doesn't automatically downgrade to system — the gateway needs to add support, or you'll need a different provider for that workload.

My tool calls work but the tool name comes back empty. What's going on?

This has been reported specifically with gateways that split streamed tool_calls across multiple chunks but only send the name field on the first one instead of repeating it — see Discussion #3767. Disabling streaming, if your gateway supports a non-streaming path, is the most reliable workaround right now.

Is the Alibaba Cloud Qwen/Bailian compatibility issue officially confirmed?

No — as of August 21, 2026 it's based on community reports in GitHub Discussions, not a confirmed root-cause statement from either DeepSeek Harness or Alibaba Cloud. Treat it as a known pattern worth checking for, not a guaranteed diagnosis, and expect it may be addressed in a later release on either side.

Where do I report a gateway compatibility bug?

GitHub Issues are disabled on the repository; use GitHub Discussions instead, and include your --dump-config output and gateway name so others can confirm whether it matches a known issue.

Next steps

Start with Use OpenAI, Anthropic, or Any OpenAI-Compatible API with DeepSeek Harness if you haven't finished initial provider setup, and Setting Up Your DeepSeek API Key and Models for credential storage details. For broader install and runtime issues beyond gateway errors, see DeepSeek Harness Troubleshooting, and check Upgrading DeepSeek Harness before assuming a gateway error is new rather than version-related. Browse more provider and gateway plugins in Models & Providers, or search all plugins for gateway-specific tooling.