Skip to content
中文
☰
Tutorial / Step 7

Troubleshooting Installation and Startup

Locate problems along the shortest path, from Node, ports, and networking to model configuration and workspace permissions.

Answer in brief

Locate problems along the shortest path, from Node, ports, and networking to model configuration and workspace permissions.

The goal of troubleshooting is not to try every fix at once, but to determine which layer the problem is in as quickly as possible.

The Command Won’t Run

Start with:

node --version
npm --version
npx @deepseek-ai/dsh --help

If Node is missing or too old, fix the runtime first. If npm downloads fail, then check your corporate proxy, Registry, certificates, and network policy.

The Web UI Won’t Open

Confirm the terminal process is still running and check the URL actually printed in the logs. The default port may be occupied by another process or blocked by security software.

Don’t kill all Node processes just to “solve a port problem.” Identify the specific listening process and project first.

The Session Editor Is Unavailable

Check whether a workspace has been selected. The official Web UI guide notes that the new interface does not enable the session editor until a workspace is selected.

Model Requests Fail

Check in order:

  1. Provider and model ID.
  2. Whether the API Key is valid and has quota.
  3. Whether the Base URL is correct.
  4. Whether the network can reach the endpoint.
  5. Whether both plain chat and tool calls fail.

Keep HTTP status codes and error types, but remove Keys, private data in request bodies, and local absolute paths before sharing logs.

Fails to Start After Installing a Plugin

  • Check the compatible versions in the Plugin README.
  • Verify the package name and publisher.
  • Check whether it depends on a specific Bundle or config line.
  • Temporarily remove the newly added Plugin and confirm the base Profile recovers.
  • Don’t modify multiple configuration layers in a row without backups.

If you can’t locate the problem, prepare a minimal reproduction, your OS version, Node version, dsh version, and sanitized logs, then report it in the official Discussions or the corresponding Plugin repository.

Six-Layer Diagnosis

LayerMinimal probe
RuntimeNode version and dsh help
StartupListen address and reachable UI
ProviderOne plain-text request
WorkspaceRead one known small file
Tool/policyOne harmless tool call
Plugin compositionDisable the newest row and compare

Change one layer at a time. A reproduction should include exact versions and launch command, clean-workspace steps, expected and actual behavior, a redacted error, and whether the problem survives without third-party Plugins.

After two changes without new evidence, restore the last known-good state and restart from the minimal probes.

Primary sources