DeepSeek Harness Model List Refresh and Fallback Rules
“Saved” applies the DeepSeek Harness model configuration, not the model list. The request path uses the new key immediately, while the catalog loads when models are first needed, refreshes in the background about every ten minutes, and falls back to built-in models if loading fails (source). Separating config activation from catalog refresh explains most “the new model never appeared” reports.
DeepSeek Harness: Three moments: save, first need, ten minutes later
The catalog has three moments, and each produces a different symptom. The timeline is (source):
| Moment | What happens | What you see |
|---|---|---|
| Save the key | Config is written, routing is usable | Card state changes, list may not |
| First model need | Published list loads | Models appear in the selector |
| About every ten minutes | Background refresh | New models gradually appear |
These explain why the selector looks old right after saving, why a model appears later, and why a usable selector can exist even when loading failed.
The moments also tell you whether waiting is useful. Waiting for a new model makes sense. Waiting for an existing model to “activate” does not; send a request. Waiting for a failed fallback to become a full list will not help; fix the network or endpoint.
“About every ten minutes” is a background rhythm, not a countdown. You will not see a change exactly on the tenth minute. Judge by the selector, not by a stopwatch.
DeepSeek Harness: Saving applies the config, not the list
Saving applies “which provider and credential to use,” not “which models exist.” The docs say model changes take effect on the next request without a server restart (source).
A practical consequence: if you switch to an already known model, send a request immediately; do not wait for a refresh. If you are waiting for a newly published model, saving the key will not make it appear; wait for the load or background refresh.
“Saved successfully” and “new model visible” are two paths. The first is configuration; the second is catalog sync. Mixing them leads to repeated saves and restarts that never change the selector.
When in doubt, look at the model selector, not the settings card. The card and the selector use different display rules, covered below.
DeepSeek Harness: Why a failed load still lets you work
A failed load still lets you work because DeepSeek Harness falls back to built-in models. The list loads on first need, refreshes in the background, and falls back when it cannot load (source).
Fallback is about availability, not freshness. It keeps requests working when the network or endpoint is temporarily down, at the cost of missing the newest models. The selector shows usable built-ins, not necessarily the published inventory.
Two signals show a fallback: the expected new model is missing, and reloading later adds more models. If only a fixed built-in set ever appears, the published list never loaded; check network, endpoint, and key instead of waiting ten minutes.
Do not restart repeatedly to “try again.” Fallback is a design behavior, not an error message. Restarting reruns the same load; if the cause is unchanged, the result is unchanged.
This is different from an incomplete-list bug, where loading succeeds but fields or filters are wrong. See DeepSeek Harness model list incomplete.
DeepSeek Harness: Card shows built-ins; new models enter the selector
The card showing built-ins does not prove the catalog is stale; it is the display rule for the published-list mode. The docs say the card shows built-in models when using the published list, so newly published models only appear in the selector (source).
This is a common false alarm. The card still shows the familiar built-ins, so the list looks unchanged, while the selector already contains the new model.
Why the split? The card is a configuration entry and shows a stable built-in set. The selector is “what can be used now” and absorbs the published list. Different jobs, different displays.
A real check: look for the new model in the selector first. If it is there, you were looking at the wrong surface. If it is absent there too, move to the load and fallback path.
DeepSeek Harness: Custom catalog vs restore defaults
Custom catalog and restore defaults are opposite actions: one stops following, one follows again. Editing the catalog uses your list and stops following the published list; restoring defaults follows it again and reloads (source).
| Action | Published list | Override | Use when |
|---|---|---|---|
| Edit catalog | Stops following | Keeps your entries | The gateway exposes a fixed set |
| Restore defaults | Follows again | Removes the whole override | You want the official list back |
Restore defaults removes the entire catalog override, including other model edits. The docs warn to use it only when restoring the whole catalog. To change one model, edit that model rather than restoring everything.
Two common misuses:
- Restoring defaults to fix one model — wipes every manual catalog change.
- Editing the catalog to follow the published list — editing itself stops following, so it moves you further away.
Ask one question: do you want the official list back, or a list you maintain? Restore for the first, edit for the second.
A custom catalog fits gateways without a standard model list, or deployments that expose only a few models. It costs maintenance: you own model IDs, context windows, and updates.
DeepSeek Harness: Verification: align three surfaces
Verify with three surfaces, not one. Three steps (source):
- Selector — the target model appears and can be selected.
- Card — it shows built-ins or a custom catalog, matching the current mode.
- Request — a short task with the target model returns.
The expected relation: the selector reflects what is usable now; the card reflects the configuration mode; the request proves the model works. When they disagree, trust the request first, then the selector, then the card.
If the selector has the model but the request fails, the problem is credential or endpoint, not the list. If neither selector nor card has it, the problem is loading or a custom catalog. If the selector has it but the card does not, it is usually a display-rule difference, not a fault.
Refresh is a background behavior; you do not restart the process to trigger it. Pick the right observation point instead of repeatedly saving.
The normal catalog lifecycle ends here. Saved keys that stay hidden and session-scoped model switching are covered next.
Watch the selector, not the clock; that is the whole trick to catalog refresh.
FAQ
DeepSeek Harness does not work that way. The DeepSeek Harness config applies on the next request, while the model list loads the first time models are needed and refreshes in the background about every ten minutes.
DeepSeek Harness falls back to built-in models when the published list cannot load. Requests still work, but the selector may not show the newest models.
In DeepSeek Harness, a custom catalog stops following the published list and uses your entries. Restoring defaults follows the published list again, reloads it, and removes the whole catalog override.
When using the published list, the DeepSeek Harness card displays built-in models by design. Newly published models appear in the model selector, so check the selector rather than the card.
Related Terms
- model catalog
- A model catalog is the DeepSeek Harness list of models available to the selector; it can follow the published list or use a custom override.— DeepSeek Harness docs - Configuring models
- published list
- The published list is the model inventory exposed by the DeepSeek API; DeepSeek Harness follows it when the default endpoint and a saved key are used.— DeepSeek Harness docs - Configuring models
- built-in fallback
- Built-in fallback is the DeepSeek Harness behavior of using a bundled model set when the published list cannot be loaded.— DeepSeek Harness docs - Configuring models
- restore default models
- Restore default models is the DeepSeek Harness action that removes the catalog override, follows the published list again, and reloads it.— DeepSeek Harness docs - Configuring models
Sources
- DeepSeek Harness docs - Configuring models· deepseek-harness
- DeepSeek Harness reference - API key provider· deepseek-ai