Your DeepSeek Harness agent was running fine against a custom provider, and then a request came back with UNKNOWN_MODEL. Or MISSING_CREDENTIAL. Or the model picker’s “Fetch available models” button returned 401. Each of those is a typed error from the provider layer, and each maps to one specific piece of configuration you can fix—which field, and how, is what this deepseek harness error guide covers.
This is the troubleshooting counterpart to the custom model guide (how to configure a provider correctly) and the finale for the provider side of this cluster: it takes the official troubleshooting table from the Modellix DeepSeek Harness docs, explains every row, and adds the credential-recovery semantics from the dsh-modellix README that decide when a key is really invalid. The pillar article for this cluster covers what the harness is and how to run it. Modellix operates the gateway these examples use, so we have a commercial interest in this working for you. Every statement below was verified against the docs and the README on September 1, 2026.
DeepSeek Harness provider errors, decoded
When a request reaches a custom provider and fails, the harness reports a typed error rather than a bare HTTP status. The Modellix integration docs maintain a four-row troubleshooting table that is the complete set of provider-level errors on this path:
| Error | What the docs say |
|---|---|
MISSING_CREDENTIAL |
Store the provider key through the Models page, or provide the referenced environment variable |
UNKNOWN_MODEL |
Select a configured model, or add the missing model to the custom provider |
| Fetch available models returns 401 | Check the key. Model discovery calls GET /v1/models on https://llm.modellix.ai/v1; enter models manually if needed |
| Request rejected with an image | Modellix LLM is a text gateway—use text-only prompts; do not attach images |
Read those rows against the fields of a provider—credential, base URL, protocol, models list—and each error points at one misconfigured field:
| Error | Most likely misconfigured field | The fix |
|---|---|---|
MISSING_CREDENTIAL |
Credential / apiKeyEnv |
Store the key through the Models page, or set the referenced environment variable |
UNKNOWN_MODEL |
models list |
Add the missing model to the custom provider, or select a configured one |
| Fetch available models returns 401 | API key | Check the key in the Modellix console; enter models manually if needed |
| Request rejected with an image | Prompt content, not configuration | Remove the image attachment and resend text-only |
That error-to-field mapping is the whole value of the table: none of these rows means “the gateway is down” or “retry the request.” Each one is configuration feedback. The next four sections go row by row, and the section after them covers the one rule that decides whether a failing key is actually broken.
The four rows of the official troubleshooting table, each mapped to the field it points at: credential, models list, API key, and prompt content.
MISSING_CREDENTIAL: the provider has no key
MISSING_CREDENTIAL means the provider is configured but no key is attached to it. The harness resolves the credential per request—from the Credential service (what the Models page writes) or from the environment variable a provider block references via apiKeyEnv. If neither exists at request time, the request fails before it reaches the gateway.
The fix has two sides, matching the two key sources documented in the Modellix getting-started guide:
- Key stored through the Models page: open Settings → Models, add the provider key, save. After saving, the page shows only a redacted descriptor, never the key itself.
- Key referenced by environment variable: make sure the variable is actually set in the harness launch environment. A provider block declaring
apiKeyEnv: MODELLIX_API_KEYwill not read your shell profile unless the harness process was started with that variable exported.
If the key came from the environment, the UI cannot repair it: if an environment-sourced Key is invalid, update MODELLIX_API_KEY in the launch environment and restart Harness; the UI cannot override it.
One boundary keeps this page honest: where keys live and how to rotate them is a different topic from why requests fail. A separate article in this series covers storage and ownership; this one stays on the error and recovery side.
UNKNOWN_MODEL: the models list is the catalog
UNKNOWN_MODEL is the most common provider error, and its usual cause is a misunderstanding about what the models list does. In custom provider configuration, the list does not filter a bigger built-in catalog—it replaces the route’s catalog. Every model the route should serve must appear in the list, and a model the route does not configure fails with UNKNOWN_MODEL.
A concrete example: you configure the provider with openai/gpt-5.6-sol and deepseek/deepseek-v4-flash, then later edit settings.yaml down to just the DeepSeek entry. A saved session that earlier used openai/gpt-5.6-sol resumes, asks for a model the route no longer configures, and the request fails with UNKNOWN_MODEL. The fix is always the same: add the missing model to the custom provider, or select a configured one.
Two details keep coming up in harness troubleshooting threads:
- Model IDs must be the full gateway IDs, including the provider prefix—
openai/gpt-5.6-sol, notgpt-5.6-sol. The harness sends the string unchanged, and the gateway routes on the full ID. - The canonical list of valid IDs is the live Models & Pricing page, and it changes as providers release models. If your list was correct last month, check it against that page before assuming the gateway changed.
How to build the models list correctly in the first place—the form fields, the settings.yaml block, and the full current catalog—is the custom model guide’s job. This page covers what the error means and how to read it back to your configuration.
“Fetch available models” 401: the key is wrong
The model picker’s “Fetch available models” button does a live query: it calls GET /v1/models on the gateway’s base URL (https://llm.modellix.ai/v1). When that call returns 401, the gateway rejected the key. The docs are direct about the fix: check the key; enter models manually if needed.
A 401 here means one of two things:
- The key is wrong, expired, or revoked—check it in the Modellix console (linked in the docs prerequisites), or
- The key is a vendor platform key (OpenAI, Anthropic, or DeepSeek platform) rather than a Modellix key. A vendor key does not authenticate against
llm.modellix.ai.
One protocol detail that is easy to mistake for a 401: model discovery only reads OpenAI-compatible GET /models endpoints. If the provider uses api: anthropic-messages, discovery cannot list models at all and you must enter the model IDs by hand. That is the protocol’s documented limit, not an authentication failure.
A 401 on model discovery is the clearest “the key is wrong” signal the harness gives you, which makes it the right place for the next section: what a 401 does—and does not—mean for your key’s validity.
401 ≠ broken key: what actually marks a Credential invalid
This is the part most troubleshooting pages get wrong, and it is worth slowing down for. The dsh-modellix README defines exactly which response invalidates a credential:
Only HTTP 401 marks a Credential invalid. HTTP 402, 429, network failures, and 5xx retain their own recovery states. Concurrent 401 responses are coalesced into one Credential dialog.
Read that literally: the recovery flow—the UI that asks you for a new key—opens only on an explicit HTTP 401 from Modellix. Every other failure keeps its own recovery state, and none of them means “your key is broken.” The plugin’s user guide documents what each state means:
| State | Meaning / next step |
|---|---|
| 402 | Check account status in Modellix |
| 429 | Wait for the rate limit window |
| Offline / timeout | Restore connectivity; do not assume the Key is invalid |
| 5xx | Service error; retry only when the operation is safe |
| Unknown generation/upload result | Inspect the task/transcript/Modellix record before any manual repeat |
Two practical consequences follow. First, when a request fails with 429 or a network error, replacing the key will not help—the key was never the problem, and no recovery dialog appears because nothing marked it invalid. Second, when several requests fail with 401 at the same time, you get exactly one credential dialog, not one per request; concurrent 401s are coalesced.
The recovery dialog also has defined behavior around what is already on screen. If a key editor is already open, it keeps its lease and upgrades in place instead of competing with a second modal. If a normal dialog—a delete-confirmation prompt or the enlarged image viewer, for example—is open, the recovery prompt waits for it to close rather than stacking another modal on top. None of this changes what you have to do, but it explains why the dialog sometimes appears late, or not at all.
The 401 rule in one diagram: an explicit 401 opens the single credential dialog; 402, 429, offline, and 5xx each keep their own recovery state and never mark the key invalid.
DeepSeek Harness Integration Docs
Read the full DeepSeek Harness configuration reference for the Modellix LLM gateway, including the troubleshooting table and the credential recovery semantics.
View Docs“Request rejected with an image”: a text gateway, not a config error
The fourth row of the troubleshooting table is easy to misread as a configuration problem, and it is not one:
Modellix LLM is a text gateway—use text-only prompts; do not attach images.
If a request is rejected with this message, the request carried an image attachment. The gateway is text-only, so no settings change, key rotation, or model swap fixes it. Remove the attachment and resend.
One source of confusion deserves a direct note: the catalog includes model IDs that look multimodal—deepseek/deepseek-v4-flash-vision is a real entry on the Models & Pricing page. The gateway constraint still applies. Even though the model card lists image modality, the Modellix LLM gateway is a text gateway and rejects attached images; the harness keeps telling you so until the prompt is text-only. The gateway’s LLM API guide spells out the request formats that do work.
When the error is not the provider
Not every error you will see in DeepSeek Harness is a provider error, and the four rows above cover only the provider layer. The boundary matters because the fix differs in kind:
- If the harness will not start, a plugin fails to load, or an install command errors, you are in install-time territory. The plugin installation guide covers install, verify, and remove, and the plugin article explains bundles, manifests, and why some errors are structural rather than configurable.
- If requests reach the provider but fail in the agent loop—unknown tool names,
400 INVALID_REQUEST-style tool-call rejections, replay errors—those are harness runtime errors, not provider errors. They are outside the four-row table, and this article deliberately does not interpret them; the official DeepSeek Harness repository and the harness’s providers guide are the right starting points.
For the generic “deepseek harness not working” case, the diagnostic order that resolves most reports is: read the exact error text (the harness reports typed errors, not bare status codes, and when the UI message is vague the session log carries the real status) → check whether it is one of the four rows above → if it involves the key, apply the 401 rule from the previous section → if it involves a model, check the models list → if none of those apply, treat it as a harness runtime issue rather than a gateway issue.
That is not a claim that these four errors are the only errors you will see—the harness has plenty of its own. It is a scope statement: the provider layer’s errors are exactly the four rows, and the recovery semantics are exactly the 401 rule. For the wider category, the agent harness overview places this cluster in context, and the sibling guide on web search and fetch covers the web-tools seam where provider errors look similar.
Open the Modellix Console
Log in to check your key status in the Modellix console, or create a new key if a 401 marked the current one invalid.
LoginFrequently Asked Questions
What does MISSING_CREDENTIAL mean in DeepSeek Harness?
The provider is configured but no key is attached to it. The harness resolves the credential per request from the Credential service or from the environment variable the provider references; if neither exists, the request fails with MISSING_CREDENTIAL. Store the key through the Models page, or provide the referenced environment variable.
Why do I get UNKNOWN_MODEL even though the model exists on Modellix?
Because the models list in your custom provider replaces the route’s catalog—it is not a filter. If the model ID is not in the list, the route does not configure it and requests fail with UNKNOWN_MODEL. Add the full ID (including the provider/ prefix) to the list, or select a configured model.
What does a 401 on “Fetch available models” mean?
Model discovery calls GET /v1/models on the gateway with your key, and a 401 means the gateway rejected it: the key is wrong, expired, revoked, or a vendor platform key rather than a Modellix key. Check the key in the Modellix console, and enter models manually if needed.
Is a 429 rate limit the same as a bad key?
No. Only an explicit HTTP 401 marks a credential invalid. A 429 keeps its own recovery state—wait for the rate limit window—and does not open the credential recovery flow. Replacing the key will not fix a 429.
Can I send images to the Modellix LLM gateway from the harness?
No. Modellix LLM is a text gateway—use text-only prompts; do not attach images. A request that carries an image is rejected regardless of the model selected, even when the model card lists image modality.
How do I update an environment-sourced MODELLIX_API_KEY?
The UI cannot override it. Update the variable in the harness launch environment and restart Harness; environment-sourced keys are read-only in the UI, so the change happens outside the harness.
Will I get one credential dialog per failed request?
No. Concurrent 401 responses are coalesced into one credential dialog. If a key editor is already open, it upgrades in place; if another dialog is open, the recovery prompt waits for it to close instead of stacking another modal.
The four-row troubleshooting table and the 401 recovery semantics reflect the Modellix DeepSeek Harness documentation and the dsh-modellix README as of September 1, 2026, and both change as the harness and plugin evolve; the live Models & Pricing page is the source of truth for model IDs. Modellix operates the gateway described here and has a commercial interest in it. Access image and video models, including the leading Chinese models, through a single API key at modellix.ai.
