Skip to content

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:

  1. confirm host/port target
  2. verify ALPHABASE_SERVER_PASSWORD and client credentials
  3. refresh diagnostics and retry

Task stops without final completion response

Checks:

  1. inspect runtime logs in failure window
  2. verify tool failure paths emit terminal/handover state
  3. confirm stream completion event reached client

Output appears malformed in response area

Checks:

  1. confirm write/edit tool completed
  2. verify artifact block parsing did not degrade to plain text
  3. retry with minimal deterministic prompt

Diagnostics panel shows unavailable capabilities

Checks:

  1. refresh capabilities
  2. verify provider credentials and upstream reachability
  3. verify local dependencies (for local AI paths)

Log Locations

  • macOS/Linux: ~/.local/share/alphabase/log/
  • Windows: %USERPROFILE%\\.local\\share\\alphabase\\log