Common problems and diagnostic checklist

Record the current version and launch method before treating the symptom. Do not paste API keys, a complete .credentials.yaml, or .env contents into diagnostic output.

Basic diagnostic commands

dsh --version
dsh web --help
dsh --profile web --dump-default-config
dsh --profile web --dump-config

For a source checkout, also check:

node --version
pnpm --version
pnpm run build

Frequent symptoms

Symptom	Likely cause and fix
Web input is disabled	No workspace is selected. Click Select workspace and choose a directory.
Default port is in use	Run dsh web --port 3081.
Modules or frontend artifacts are missing	Run pnpm run build from the repository root and retry.
The UI still shows old source	The launcher does not detect stale artifacts; rebuild manually.
MISSING_CREDENTIAL	Save credentials in model settings or provide the environment variable referenced by the configuration.
INVALID_CREDENTIAL	Correct the stored value; the error does not reveal the secret itself.
UNKNOWN_MODEL	Select a configured model or add it to the custom provider.
Fetching models returns 401	Check the credential; enter models manually when GET /models is unsupported.
Credential file permission error	Run chmod 600 ~/.dsh/.credentials.yaml.
--host 0.0.0.0 is rejected	The current CLI deliberately disallows all-interface binding; use 127.0.0.1.
Headless immediately shows usage	Provide a non-empty task.
Fields disappear after a patch	A patch replaces the target entry’s complete config; it is not a deep merge.

Before publishing logs

--dump-config should not print a literal API key, but it may still contain local paths, provider IDs, and environment structure. Review it manually before posting it to a public issue.

Do not bypass the 0.0.0.0 restriction through a reverse proxy or source modification. The current Web surface has no authentication layer, so public exposure increases remote-code-execution risk.