Troubleshooting DSH

Close the terminal and open a new one, then run node --version and npm --version. If either still fails, repair the Node.js installation or PATH before retrying DSH.

The current upstream repository declares ^22.19.0 || >=24.0.0. Compare that range with node --version. A machine can have “Node 22” and still be too old, for example 22.17. Upgrade Node before debugging a downstream package or build error.

On the first launch, npx may need to download the package before DSH can start. Keep the terminal open until it prints the Web UI address or a real npm/network error. Do not repeatedly start several copies, because a second copy can create a port conflict that hides the original problem.

Another process is already listening on port 3080, often an earlier DSH process. On Windows PowerShell, inspect it with Get-NetTCPConnection -LocalPort 3080 -State Listen. On macOS/Linux, use lsof -nP -iTCP:3080 -sTCP:LISTEN. Stop the stale process or start DSH on another port, for example npx @deepseek-ai/dsh web --port 13080.

On machines using Hyper-V, WSL2 or Docker Desktop, Windows can reserve a TCP range that includes 3080. Check with netsh interface ipv4 show excludedportrange protocol=tcp. If 3080 falls inside an excluded range, choose a port outside it, for example npx @deepseek-ai/dsh web --port 13080. This is different from EADDRINUSE: there may be no process to kill.

Read the final terminal lines first. If the error is from npm or package download, treat it as an installation/network problem. If DSH itself prints a configuration or plugin-tree error, fix that exact message before restarting.

A local launch normally hands the URL to the default browser after the Loader tree is ready. You can always open the printed URL manually. Under SSH, not opening a browser is expected: DSH prints the host URL and leaves the forwarded/local address to the SSH client or editor. Use --no-open when you intentionally want to suppress browser launch.

Open Settings → Models, enter the credential for the provider selected by the failing session and save it. The built-in DeepSeek key is stored in $DSH_HOME/.credentials.yaml; the UI receives only a redacted descriptor after saving.

Select a model that currently exists under the configured provider, or add the missing model to a custom provider. Do not rely on a model name copied from an old screenshot.

A credential reached the provider but was rejected. Confirm that you pasted the key itself and that it is still valid. For custom providers, model discovery can also return 401 because it calls an OpenAI-compatible GET /models endpoint.

apiKeyEnv names an environment variable; it is not the secret itself. DSH inherits the environment when the process launches. If you export or edit that variable after DSH is already running, restart DSH from the shell that contains the variable.

Select a configured provider and model. This can happen when a saved default points to a provider that was deleted. A session that has already sent a request retains the model recorded in that session log; changing the default mainly affects new sessions.

A manually added custom model is treated as text-only until its configuration declares image input. The official DeepSeek chat-completions route is text-only and cannot be converted into a vision route by changing this flag.

Check that the DSH terminal process is still running and use the address it actually printed. If startup failed with EADDRINUSE or EACCES, resolve the port error first instead of repeatedly refreshing the browser.

A fresh Web UI has three separate readiness steps: save a provider credential, select a workspace, and select a model. The directory where you started DSH is only its initial filesystem location; it is not automatically a selected workspace. Click Choose workspace and select it explicitly.

Do not copy that flag into the current shipped CLI. The current official CLI behavior reference says the Web alias intentionally does not support --host 0.0.0.0 yet. For remote use, prefer an SSH/editor forwarding path or another deployment method explicitly supported by the version you are running.

Open the selected workspace outside DSH and verify the file directly. Check that you selected the folder you intended and that the requested path was inside that workspace.

Use a test folder owned by your normal user. Do not begin with protected system directories or a workspace that requires elevated permissions.

The official dsh plugin command forwards package operations to pnpm, so pnpm must be available on PATH for CLI plugin changes. This is separate from the simple npm quick-start, which does not require pnpm just to run the Web UI.

A Git-hosted source plugin can run a prepare build during installation. pnpm 10+ can block that until the consumer explicitly allows the build in the profile's pnpm-workspace.yaml. Treat that prompt as permission to execute third-party install-time code: review the source first and do not approve it just to make the error disappear.

Adding, removing or updating a Bundle changes the profile on disk, but a running profile keeps the Bundle set from its current start. Restart the profile or DSH Desktop after Bundle membership changes.

Be explicit about the target profile when using the CLI. Profiles have their own dependency and Bundle composition; installing into one profile does not silently copy the plugin into another.