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.

Node requirements depend on the DSH version. The historical source snapshot declared ^22.19.0 || >=24.0.0; v0.2.2-alpha.2 requires >=24.9.0. Compare the installed package requirement with node --version before debugging downstream errors.

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.

Fixed in v0.2.1-alpha.5 (prerelease). Enable or disable a plugin, then reopen the current session’s / menu and check the skill list. If it remains stale, record the DSH version, plugin name and reproduction steps. Read the release notes →

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.

Fixed in v0.2.1-alpha.5 (prerelease). This release also reduces duplicate queries when creating or restoring multiple terminals.

After upgrading, check whether switching panels still triggers repeated retries. If it does, record the DSH version, terminal error and panel-switch sequence. Read the release notes →

A Windows user reported missing workspace records, sessions and plugin state in DSH_HOME after updating from 0.2.1-rc.5 to 0.2.2-rc.1; project files remained. The reported cause is a user hypothesis and remains unconfirmed upstream. Back up the actual DSH_HOME before updating. If data is already missing, stop writing to that location, check existing backups and preserve logs. #12290

Another Windows user reports that opening an older session after upgrading to 0.2.2-rc.1 removes it from the sidebar and disables the composer; the report says its event logs remain intact. This differs from the data-loss report above and does not establish a shared cause. Back up session data, record the version and error, and follow the upstream investigation; do not delete the session files. #12277

Two users reported that workspaces or DSH_HOME inside a custom installation directory were deleted when updating from 0.2.1-rc.2 to rc.3. The cause and scope have not been confirmed by maintainers. Before updating, keep workspaces and data outside the installation directory and back them up separately. If data is already missing, stop writing to the affected location and check existing backups. #10851 · #10975

Windows and macOS users report authentication cookies accumulating after repeated launches of rc.2 or rc.3, sometimes causing startup failure or HTTP 431. This is user investigation, not a confirmed cause for every similar error. Record your version, OS and error logs, back up data and follow the upstream discussions. Cookie clearing in those reports is not an officially confirmed fix. #11366 · #11397

A user reports a frozen window after launching rc.3; the cause and remedy await upstream confirmation. Record the version, OS and symptoms, save diagnostics and follow the discussion. Do not disable core UI components as a fix. #11283

Check the endpoint shown in the error. The plugin defaults to https://api.deepseek.com/v1/tools. The gateway must route /v1/tools/search and /v1/tools/fetch. If deployment uses a prefix such as /api/v1/tools, include it in the full base URL.

Add the gateway routes or use an API base that supports both endpoints. To restore Messages search and local HTTP fetch, turn off the new API in Web search settings and save.

For missing credentials, check this plugin’s apiKeyEnv reference, which defaults to DEEPSEEK_API_KEY. API keys use Authorization: Bearer. If a DeepSeek account session receives 401, follow the error’s sign-in instructions.

Transport, HTTP and response-format failures use this code. Check the endpoint and HTTP status. A failed Fetch API status describes retrieval failure; it does not report the target page’s HTTP status.