Fix common dsh errors

Install & environment

ERR_PNPM_FETCH_404 package not found

Your npm registry mirror lags behind the official one, so a just-published package returns 404.

dsh plugin add <package> --registry=https://registry.npmjs.org

'pnpm' is not recognized pnpm is missing

dsh plugin forwards to pnpm, which isn’t installed.

npm install -g pnpm

node: command not found Node.js not on PATH

The dsh launcher needs Node.js on your PATH. Add your Node folder (and npm global bin) to PATH. Find them with npm prefix -g.

npx @deepseek-ai/dsh fails to install

Usually a registry lag or a native dependency without a prebuilt binary. On Linux, node-pty ships no prebuilds, so it needs a compiler toolchain to build from source.

npx @deepseek-ai/dsh --registry=https://registry.npmjs.org

Install build essentials (build-essential python3 on Debian/Ubuntu) and use a Node LTS, then retry.

Port 3080 already in use stale process holds the port

A stale dsh process holds the port — the page even loads but talks to the old instance, so config changes never appear.

dsh web --port 8080

Kill the old process first, or use a fresh port.

Credentials & models

MISSING_CREDENTIAL no API key stored

No API key is stored. Set it in Settings → Models, or in ~/.dsh/.credentials.yaml:

DEEPSEEK_API_KEY: sk-your-key-here

UNKNOWN_MODEL model not configured

You picked a model that isn’t configured. Add it to your provider, or select a configured model.

"Get available models" returns 401 wrong key or base URL

The key is wrong — model discovery calls the OpenAI-compatible GET /models endpoint. The three settings (base URL, key, model name) must all match.

maximum context length is 1048576 tokens context window exceeded

The conversation plus the completion you asked for exceeds the model’s context window.

Start a new session, shorten the system prompt, or lower max_tokens. On a long session, summarize and continue fresh rather than pushing the window.

Plugins

Plugin installs but doesn’t activate missing dsh.bundle manifest

The package has no dsh.bundle manifest, so dsh plugin add installs it as a plain dependency that never loads. The plugin must ship a cordis.patch.yml and declare dsh.bundle.patch in its package.json.

ERR_REQUIRE_ESM plugin built as CommonJS

The plugin was compiled to CommonJS but depends on ESM-only packages like @deepseek-ai/dsh-tools. The plugin must be built as ESM ("type": "module").

cannot get property "systemPrompt" without inject missing inject declaration

Plugin code calls ctx.systemPrompt without declaring inject: ["systemPrompt"]. It’s a plugin bug — report it to the author with this exact message.

allowBuilds prompt git-hosted plugin build script blocked

A plugin installed from GitHub ships a prepare build script, which pnpm blocks by default. Add the key pnpm prints to allowBuilds in pnpm-workspace.yaml, then re-run.

"@deepseek-ai/dsh-type-meta" not found dependency not published yet

A plugin depends on a package that isn’t published to npm yet. Nothing you can do client-side — the author must publish it first.

reading 'prepare' of undefined duplicate dsh-tools instance

A plugin’s peer-dependency pulls a second copy of @deepseek-ai/dsh-tools, so internal symbol-key lookups collide and tool scheduling crashes.

Make @deepseek-ai/dsh-tools a single shared dependency (peer or bundled once), or ask the author to fix the peer range.

duplicate loader entry id bundle dependency promoted twice

dsh plugin add promoted a pre-existing bundle-declaring dependency into the bundle stack, creating a duplicate entry id.

Remove the duplicate entry from your profile’s bundle config, then re-add the plugin.

Failed to load plugins fatal plugin mount screen

A plugin fails to mount at boot and the UI offers no recovery action.

Move the offending plugin out of the profile (or reset the profile), then restart. Re-add plugins one at a time to isolate the culprit.

Runtime & web UI

Web UI send button stays disabled no workspace selected

The web profile requires a workspace before sending. Click Choose workspace and select a directory.

Skills work in the CLI but not the web UI profile capability mismatch

The web profile ships with tool-skill and skill-filesystem disabled; the headless/CLI profile has them on.

crypto.randomUUID is not a function plain HTTP breaks Web Crypto

The Web Crypto API is only available on secure contexts. Accessing the web UI over plain http:// (LAN IP or phone) breaks it.

Use https:// or localhost, or put a TLS reverse proxy in front of the web UI.

Composer input box disappears broken markdown image reference

Deleting a markdown image reference in a draft can blank the input box.

Refresh the page. If it recurs, report it with the repro steps.

/api/commands/list returns 404 command menu empty

The plugin manifest auto-discovery broke, so commands never registered.

Reinstall the plugin and restart the web UI; report it if it persists.

Skill menu only matches by prefix middle words unfindable

Skill search matches names by prefix, so middle words are unfindable.

Type the skill name from the start, or browse the full skill list.

Settings → Plugins blank over remote access local-only plugin manager

When you open the web UI from another machine (over a LAN IP or tunnel), the Settings → Plugins panel silently renders blank — plugin management is local-only, but nothing tells you that.

Manage plugins on the machine where dsh runs, at http://127.0.0.1:3080. Remote browsers can chat, but plugin add/remove has to happen locally.

Sessions & cache

Session log corrupted on resume sequence gap in append-only log

On resume, the last committed events re-append with fresh timestamps, creating a sequence gap in the append-only log.

Export your data, then open a fresh session instead of resuming the corrupted one.

KV cache hit rate collapses after resume system-prompt ordering drift

System-prompt section ordering drifts on resume, dropping cache hits to near zero.

Start a clean session rather than resuming, and keep your preset order stable.

History "Failed to fetch (internal)" corrupted session deltas

A session with malformed streamed tool-call deltas can’t be loaded.

Reload; if it persists, the session file is corrupted — start fresh.

Platform-specific

SEC_E_NO_CREDENTIALS Windows sandbox breaks HTTPS

The restricted-token sandbox breaks Schannel HTTPS (curl, PowerShell). OpenSSL clients (node, python) are unaffected.

Use a full-access preset for network tasks, or route through node/python tools.

ERR_DLOPEN_FAILED sharp fails to load on Windows

A native image dependency fails to load in dev/desktop builds.

Use the workaround in the linked discussion, or switch to a pure-JS fallback.

macOS launchd env: node crash loop from missing PATH

A LaunchAgent launches without PATH, so node isn’t found and dsh crash-loops.

Add PATH and a ThrottleInterval to the LaunchAgent plist.

Windows path truncated at a Chinese character UTF-16 low byte read as NUL

Characters whose UTF-16 low byte is 0x00 (like 言) get misread as a NUL terminator, so dsh truncates the working directory at that character and files/sessions under it fail to open.

Run dsh from a path that avoids those characters (a pure-ASCII path, or a directory name without them). This is an upstream readUtf16 decoding bug — report it with your exact path.

pnpm install fails on an exFAT volume lefthook inode ownership check

On a macOS exFAT/USB volume, pnpm install aborts during the lefthook install step — exFAT doesn’t preserve Unix inodes/ownership, so the hook install check fails.

Move the project onto an APFS/HFS+ (or other journaled) volume and reinstall. exFAT is for cross-device transfer, not for running a pnpm workspace.

Still stuck? Check the install guide, the plugin guide, or the tutorial.