Troubleshooting & Error Playbook
Fast diagnostic steps for common issues across Helix Web, CLI/SDK integrations, and sandbox execution.
HTTP Error Codes Quick Reference
| HTTP Status | Cause | Resolution |
|---|---|---|
401 Unauthorized | Missing, expired, or revoked hx_* bearer token | Confirm Authorization: Bearer ... header and verify key is active under /developer/keys. |
403 principal_escalation_denied | An hx_embed_* browser token attempted an org/admin endpoint (/api/webhooks/platform, /api/helix/keys) | Call admin endpoints exclusively from your backend using hx_live_*. |
403 GitHub repo create denied | Installation token lacks administration: write or targeted a personal user account | GitHub installation tokens cannot create user-owned repos (create repo manually first) and need administration: write for org repo creation. |
429 rate_limit_exceeded | Per-key RPM/RPD cap or workspace weekly compute window reached | Back off by Retry-After seconds or raise key cap in /developer/keys. |
422 / 400 validation_error | Missing goal or malformed JSON schema | Inspect the structured issues array in the JSON response. |
Sandbox Background Servers Hang or Exit Early
- What happens automatically: Commands matching web server patterns (
next dev,vite,uvicorn,go run,cargo run,manage.py runserver,java -jar,dotnet run,streamlit run) automatically detach in the background so the command runner never blocks until timeout. - How to diagnose crashes: Inspect the
.exitstatus (HELIX_BG_EXIT:<code>) and log tail shown in the tool execution card inside Workspace. Missing.envsecrets are the #1 cause of crash-on-boot; populate them under Environments.
Long Multi-Turn Sessions & Memory Retention
- When conversations grow long, the Context Condenser compresses older turns while prepending a deterministic
<PINNED_FACTS>ledger holding:- Original mission goal + latest 5 follow-up instructions
- Verified
/workspace/...file paths and preview URLs - Active background job IDs (
bg-XXXXXXXX)
- Never worry about repeating file paths or preview ports after a follow-up —
<PINNED_FACTS>preserves them automatically across successive condensations.
Stuck Detector or Failure Budgets
- If an agent tries the exact same tool call and identical error 3 times consecutively without progress, the Stuck Detector pauses execution honestly instead of burning quota blindly.
- Send a clarifying follow-up hint right in the thread (e.g., "Use port 3005 instead of 3000") or open Open Door desktop view to inspect interactively.
Still Stuck?
- Check platform component status at /status
- Run live API tests using the OpenAPI 3.1 Explorer
- Contact support via /support with your
threadIdorrunId

