Troubleshooting

Diagnose downloads, startup, plugins, display, models, and CLI problems by symptom.

Preserve errors and logs first, then change one thing at a time. Do not start by deleting data.

First checks

1. Copy logs from Help → Run logs, or open logs/dsh-web.log in application data.
2. Record the desktop version, OS and architecture, active profile, and core version and source.
3. Confirm first-run downloads completed and check the actual service address shown in the interface.
4. Save active tasks and repository changes before restarting the app and waiting for the health check.

Find your symptom

Symptom	Try first
Download fails	Check access to Node.js, npm registry, and GitHub Releases; retry transient failures. Configure corporate proxies or TLS interception according to your organization’s requirements
Harness does not open	Read the service log; a busy default port can fall back to another available port. Check whether security software blocks loopback connections
A plugin prevents startup	Record the named plugin and raw error; use the recovery page’s individual plugin snapshot restore or removal action
Model request fails	Check credentials, balance, endpoint, and model name; see Configure a model
dsh is not found	Confirm CLI integration is enabled, then check PATH and command resolution in a new terminal; see CLI integration
Windows lacks WebView2	Install Microsoft’s WebView2 Runtime and retry
macOS blocks startup	Verify the download source, then allow the app in System Settings → Privacy & Security; also check WebView compatibility

Plugin recovery and safe mode

• Restore from snapshot is offered when an individual plugin snapshot exists; do not assume rollback is available without one.
• Remove this plugin and continue checking targets the listed plugin, not your workspaces or entire session history.
• If startup still fails, Safe Mode switches to the safe profile with only core components and built-ins.

Safe mode is for startup troubleshooting, not security isolation. It removes non-built-in plugins from the safe profile and renames unparseable patches to .broken-<timestamp>. Switch back to the original profile after recovery. Back up before resetting, deleting, or restoring over a profile.

Black window on Linux

On Wayland, try .deb first. If AppImage still shows a black window, try:

WEBKIT_DISABLE_COMPOSITING_MODE=1 WEBKIT_DISABLE_DMABUF_RENDERER=1 GDK_BACKEND=x11 ./Deepseek*.AppImage

Separate development and release environments

Debug uses ~/.dsh.dev, ignoring inherited DSH_HOME, and a dev/ runtime directory in application data. Its service log is dev/logs/dsh-web.dev.log and its preferred port is 3081; release builds prefer 3080. Both can fall back to another port. Use the logs and directories from the environment you are diagnosing.

Ask for help

• Search existing issues for the same problem first.
• If it remains unresolved, open a new issue.

Include reproducible steps, version information, and the smallest relevant log section. Remove keys, tokens, private paths, prompts, repository content, and personal data first.