Troubleshooting
Start by validating runtime health first, then app-layer behavior.
Check the affected connection
Name the affected screen, task, and exact error. Open Help → Activity → Ask Sophia for a recorded task issue. In VS Code, refresh Runtime Dashboard → Diagnostics.
The packaged desktop manages an embedded runtime whose port can change. For a manually configured runtime, use its actual host, port, and required authentication. A runtime 401 is different from a model provider rejecting its key; fix the affected connection rather than rotating unrelated credentials. Remove passwords, keys, and tokens from reports.
Common Failures
Unauthorized (401)
Likely auth mismatch between client and runtime.
Checks:
- confirm host/port target
- verify
ALPHABASE_SERVER_PASSWORDand client credentials - refresh diagnostics and retry
Task stops without final completion response
Checks:
- inspect runtime logs in failure window
- verify tool failure paths emit terminal/handover state
- confirm stream completion event reached client
Output appears malformed in response area
Checks:
- confirm write/edit tool completed
- verify artifact block parsing did not degrade to plain text
- retry with minimal deterministic prompt
Diagnostics panel shows unavailable capabilities
Checks:
- refresh capabilities
- verify provider credentials and upstream reachability
- verify local dependencies (for local AI paths)
Log Locations
- macOS/Linux:
~/.local/share/alphabase/log/ - Windows:
%USERPROFILE%\\.local\\share\\alphabase\\log