Fix CLIENT_UPGRADE_REQUIRED: upgrade DSH for newer models

CLIENT_UPGRADE_REQUIRED is not an API-key problem or a network problem; the model catalog is saying “this model needs a newer DeepSeek Harness client”. The error states the required version. The correct order is: read the requirement, identify which installation is running, upgrade it, restart, and reselect the model. Re-entering the key or renaming the model only delays the fix.

DeepSeek Harness: How to read the error

The key information is the required version, not “invalid credential”. Read it:(source)

1. Confirm the code — is it really CLIENT_UPGRADE_REQUIRED, not MISSING_CREDENTIAL or UNKNOWN_MODEL? Expected: do not mix three different failure classes.
2. Read the required version — the error states the version to install. Expected: a concrete upgrade target, not “latest”.
3. Identify the model — which model triggered the gate. Expected: you can switch to a supported model while planning the upgrade.

The gate comes from the model catalog, not the provider auth layer. For a logged-in DeepSeek account, the list comes from the account service; a model that requires a newer client fails this way.

DeepSeek Harness: Three upgrade paths

Upgrade the installation you actually run; do not mix them. Three:(source)

1. Global npm install — upgrade the global package to the required version. Expected: dsh -V reports the new version.
2. npx runtime — start with a versioned or latest npx command. Expected: watch the npx cache; an old version may be reused.
3. Desktop or source build — use the desktop updater or rebuild. Expected: desktop and CLI version boundaries are separate.

If the error names a specific version, install that version rather than latest; latest may be outside the compatibility window or may not yet include the required capability.

DeepSeek Harness: Verify after upgrading

“Installed” is not “running the new version”; verify the process. Steps:(source)

1. Check the version — dsh -V, then compare with which -a dsh. Expected: the running process comes from the upgraded installation.
2. Restart the process — stop the old dsh web or SDK host and start again. Expected: the new runtime loads.
3. Reselect the model — choose the model that failed. Expected: CLIENT_UPGRADE_REQUIRED is gone.
4. Start a new session — old sessions may keep their old model record. Expected: the new session uses the new default and returns normally.

If step 1 already shows the wrong version, resolve the multi-install conflict before debugging the application.

DeepSeek Harness: Three multi-version conflicts

A repeated error usually means “upgraded one installation, running another”. Three conflicts:(source)

1. Global vs npx — PATH has a global dsh and the npx cache has another. Expected: compare which -a dsh with the launch command.
2. Desktop vs CLI — the desktop app has its own update unit; upgrading the CLI does not change it. Expected: check both versions.
3. venv vs global — the Python SDK wheel carries a bundled runtime; upgrading the global dsh does not change it. Expected: check inside the SDK venv.

Multiple installations are fine; debugging requires knowing which one started the current process.

DeepSeek Harness: What not to do

The gate is not a configuration trick; bypassing it only changes the failure mode. Three things to avoid:(source)

1. Do not rename the model to fit — the request shape may not match. Expected: upgrade or choose a supported model.
2. Do not delete sessions — session logs are not the cause of the gate. Expected: keep them for comparison.
3. Do not randomize compat switches — those adapt request shape, not client version. Expected: read the error before touching compat.

If you cannot upgrade immediately, switch to a model supported by the current version and continue; upgrade during a maintenance window.

DeepSeek Harness: A real diagnostic chain

Go from error to cause using three columns: version, install source, model source. The chain:(source)

1. Record the required version — for example, the error names a specific version. Expected: a target version, not a blind latest.
2. Check the current version — dsh -V. Expected: see how far behind the process is.
3. Check the install source — which -a dsh, npm ls -g --depth=0, or pip show in the venv. Expected: know which installation the process uses.
4. Check the model source — account catalog or a custom provider. Expected: confirm the gate really comes from the account model list.

After these four, usually only “upgrade the correct installation” remains. If the error persists, check the model catalog cache and restart.

Temporary options and their costs

If an immediate upgrade is impossible, temporary workarounds are acceptable if you know their cost. Three:

1. Use a compatible model — pick one supported by the current version. Expected: work continues, with possibly different capability.
2. Switch provider — use an equivalent model from a third-party or self-hosted provider. Expected: request shape and quota semantics may change.
3. Pause the model — avoid the gated model until the upgrade. Expected: safest, but the capability is unavailable.

Do not rename a model or forge a version number; that turns a clear gate into a request-shape mismatch.

Back up before upgrading

Back up profiles and sessions before upgrading the dsh binary, so rollback does not lose configuration. Three steps:

1. Back up $DSH_HOME — at least profiles and sessions. Expected: a rollback baseline.
2. Record versions — current dsh -V, installation method, and package manager version. Expected: know where you came from.
3. Record models — current default and models used in active sessions. Expected: compare behavior after the upgrade.

After the upgrade, verify with a normal conversation and a model selection; “the UI opens” is not enough.

DeepSeek Harness FAQ

The model list is still stale after upgrading—what now? Restart the process and reopen the provider on the model page. The catalog may load at startup. If it still looks wrong, confirm the account service returned the model.

Does the error affect every model? No. It is per model; other models under the same provider may still work.

Desktop did not prompt for an update, but the CLI reports the error—why? They are different versions. Use the desktop updater, or pick a compatible model in the CLI; do not assume desktop follows automatically.

The short version: CLIENT_UPGRADE_REQUIRED is a version gate, not a credential failure. Read the required version, then identify the installation that is actually running.