CH 07 · Troubleshooting Cheatsheet
Chapter Goal
Once you're up and running and run into problems, don't panic — match against this map. The most common startup, config, and runtime issues all covered in one place.
Can't Start
There are only three common pitfalls for dsh web startup:
| Symptom | Cause | Resolution |
|---|---|---|
| Startup reports port occupied | 3080 is taken by another program | At launch, change port: dsh web --port 8080 (this is part of the launch command, not something you can change while running) |
| Browser didn't auto-open | Some environments won't auto-launch the browser | Manually visit http://127.0.0.1:3080 (use the corresponding port if you changed it) |
| Service quit on its own while in use | dsh service sometimes quits itself | It's not broken; just re-run when you need it |
Config-Related Errors
During model configuration, errors fall into a few categories — find your match:
| Error | Meaning | Resolution |
|---|---|---|
MISSING_CREDENTIAL | No key configured | Go to Settings → Models to store a key, or provide the environment variable it references |
INVALID_CREDENTIAL | Key format is wrong | Check your key for stray spaces or missing characters |
UNKNOWN_MODEL | Model doesn't exist or isn't configured | Check whether the Model ID is configured; also check whether this provider supports this model |
UNSUPPORTED_REASONING_EFFORT | Reasoning effort not supported | Use one of off / low / high / max |
| Fetch available models returns 401 | Key is wrong | Check the key; model discovery calls the OpenAI-compatible GET /models endpoint. For services that don't provide that endpoint, enter the model manually |
Runtime Request Errors
When a request is sent and you get an HTTP error code, it's mostly the DeepSeek server-side status, unrelated to your config. Official error code cheatsheet:
| Code | Meaning | Resolution |
|---|---|---|
| 401 | Auth failed | Check whether the API Key is valid or expired |
| 402 | Insufficient balance | Top up at the DeepSeek Open Platform |
| 422 | Parameter error | Modify the request parameters per the error message |
| 429 | Requests too frequent | Lower request frequency, wait a moment and retry (don't spam) |
| 500 | Internal server error | Wait a moment and retry; keep failing, contact the official team |
| 502 | Gateway error | Upstream model service unavailable, wait and retry |
| 503 | Server busy | Server-side load is high, retry later |
dsh also categorizes errors into a few stable internal codes (AUTH auth failure, QUOTA quota, RATE_LIMIT rate limit, CONTEXT_WINDOW_EXCEEDED context overflow, TRANSPORT network transport failure, etc.). When you see these codes, take them at face value — that's usually exactly what they mean.
Two Small Interface Pitfalls
- Model selector shows "Select a model" and the input box won't accept input: the default model you previously set points to a provider that was deleted. Just pick a model again to recover.
- Can't find a task run by headless: look in the session list under Ungrouped (CH 05 explained: files are stored by workspace, the UI display is in Ungrouped — two separate things).
The Three Go-Tos to Try First
When you hit a problem you can't quite describe, go in this order — it solves most issues:
- Check the logs: the terminal output at startup, or the redirected startup log (e.g.
dsh web > .dsh-startup.log 2>&1), the error code is right there. - Let the AI check the config tree itself: in a session, ask it to use
--dump-configto check the config, and throw the "why isn't the default model the one I want" type of question at it for it to locate (CH 05 covered this trick). - Restart the service: the dsh service quits itself anyway, so re-running often fixes it.
If all three don't save you, there are two situations based on your level:
- Total beginner (dsh is your first Agent): go to the official repo's Issues and search the same error keyword; someone has probably hit it.
- Already used tools like Claude Code or Codex: just have them help you troubleshoot.
What you learned in this chapter
- [ ] Know the three startup pitfalls (port occupied / browser not opening / service self-quit) and how to handle each
- [ ] Use the config error table to handle
MISSING_CREDENTIAL,UNKNOWN_MODEL,UNSUPPORTED_REASONING_EFFORT - [ ] Recognize the meaning of common runtime HTTP error codes (401 / 402 / 429 / 500 / 502 / 503) and basic handling
- [ ] Know that "Select a model" locking the input box means the default model points to a deleted provider
- [ ] For new problems, try the three go-tos (check logs / dump-config / restart) first