Fix DSH API key errors: MISSING_CREDENTIAL and UNKNOWN_MODEL

MISSING_CREDENTIAL in DeepSeek Harness means no API key is stored, while UNKNOWN_MODEL means the model is not configured — the former fails before the request is sent, the latter fails when the key exists but the model does not match. The root rule is that the API key, base URL and model name must all match the same provider. Fix it in three steps: store the key, check the model name, verify with one chat message.

DeepSeek Harness API key errors and when they trigger

MISSING_CREDENTIAL appears before UNKNOWN_MODEL: without any key the request never goes out; once a key exists, the model check runs and may then fail. The two messages and triggers (source):

1. MISSING_CREDENTIAL — the chat request fails right away with a "no API key stored" message. Triggered when: no key has been entered during first-time setup, ~/.dsh/.credentials.yaml has no DEEPSEEK_API_KEY, or no environment variable is exported;
2. UNKNOWN_MODEL — the request can start but the model check fails. Triggered when: the model name is misspelled, the custom provider has never been given that model, or the name is not in the provider's list;
3. Order of attack: fix MISSING_CREDENTIAL (missing key) first, then UNKNOWN_MODEL (model mismatch) — the key is the gate, the model is the next hurdle.

Why DeepSeek Harness API key errors happen: missing credential, mismatched model

The two errors have two roots — no usable credential (the key is not stored) and a model name inconsistent with the provider config — and both sit under the same rule: the key, base URL and model name must all match one provider. In detail:

1. No stored credential: when both the official Models page and .credentials.yaml are empty, the request fails with MISSING_CREDENTIAL (source); the adapter source throws exactly this code when no key is found anywhere in the chain (source).
2. Model not configured: UNKNOWN_MODEL fires when the selected model is invisible to the provider — the official docs state the fix plainly: "Select a configured model or add the missing model to the custom provider" (source).
3. All three must match: the key is issued by that provider, the base URL is its endpoint, and the model name lives in its model list — one account, one endpoint, one model set; cross-mixing always errors.

Fix DeepSeek Harness API key errors: store the key, check the model, verify

Follow the fixed order: store the key via the settings page or config file, check the model name against the provider, then send one test message to confirm all three match. Step by step:

1. Store the API key (fixes MISSING_CREDENTIAL) — GUI route: open Settings → Models and enter sk-your-key in the provider's input field, then save;
2. Or edit the config file — edit ~/.dsh/.credentials.yaml and add:
   yaml

   DEEPSEEK_API_KEY: sk-your-key
   

   Save and restart dsh so the credentials service reloads (source);
3. Check the model name (fixes UNKNOWN_MODEL) — on Settings → Models, confirm the selected model exists in the current provider's list: compare spelling character by character (case-sensitive), and for a custom provider add the model to the provider config first;
4. Check the base URL — if you use a custom gateway, confirm the base URL and key belong to the same provider; an endpoint that does not match the DeepSeek official API produces 401 (see the "fetch available models 401" guide);
5. Verify with one message — send a message in a session; a normal reply means success. If it still errors, read the code: MISSING_CREDENTIAL → back to step 1, UNKNOWN_MODEL → back to step 3, 401 → check the base URL.

How to verify a DeepSeek Harness API key config: curl test and one chat message

Do not jump straight into a chat after configuring — verify the key with a curl call first, then confirm end-to-end with one message; only when both pass is the fix complete. In order:

1. Test the key directly with curl — bypass dsh to confirm the key works on its own:

   bash

   curl https://api.deepseek.com/v1/models -H "Authorization: Bearer <your-key>"
   

   200 with a model list → the key is valid; 401 → the key is invalid or expired, back to step 1 of the fix section.

2. Check the config file — confirm the key is actually written to the credentials file:

   bash

   cat ~/.dsh/.credentials.yaml
   

   Seeing DEEPSEEK_API_KEY: sk-your-key means it is stored; a missing file means you used the GUI route earlier.

3. Environment-variable route (a third way to store the key) — to avoid touching files, export the variable before starting:

   bash

   export DEEPSEEK_API_KEY=sk-your-key
   dsh web
   

   Note: the variable lives only in the current terminal session — re-export it at the next launch.

4. One chat message as an end-to-end check — send "hello" in a Web UI session; a normal reply means the key, base URL and model name all match. If it still errors, map the code back to the fix section: MISSING_CREDENTIAL, UNKNOWN_MODEL or 401.

Notes: DeepSeek Harness — check the key before the model

1. MISSING_CREDENTIAL and UNKNOWN_MODEL are two gates: fix the key first, then the model — do not skip.
2. The environment-variable route (export DEEPSEEK_API_KEY=sk-... in the launching terminal) works too, but only for that session.
3. Always restart dsh after changing config — credentials and the model list load at startup.
4. Model errors are unrelated to plugins; installing or removing plugins does not change this three-way matching rule.
5. See install error troubleshooting for other DeepSeek Harness install issues.

Sources: dshbase troubleshooting, DeepSeek Harness providers.md, llm-deepseek adapter.ts