Skip to content
Helix
PricingDocsChangelog
Log inStart free
Documentation
Overview
Getting Started with HelixYour First Mission WalkthroughFocus Mode vs Console ModeDesktop & Mobile Companion Apps
5-Minute API QuickstartIntegrations & Autonomous ChannelsProduction Examples & Recipes
Helix Agent Overview & Autonomy TiersHelix AdvisorHelix OperatorHelix PhasesHelix Sandbox
Synthetic AI & Simulation WorkflowsDrop-In White-Label Agent EmbedsDeveloper & Embed Guide
Helix ArchitectureArchitecture & Technical GuideHybrid Compute Bridge & Custom MCPHelix MCP
MCP Providers & Cloud Connectors
REST, Gateway & MCP API ReferenceAuthentication, Keys & ScopesSDKs & Programmatic ClientsWebhooks, HMAC Verification & ReplayTroubleshooting & Error Playbook
Helix Security ArchitectureEnterprise Security, Secrets & GovernanceBilling, Compute Windows & Quotas
Developer PlatformDeveloper Console
Docs/API, SDKs & Webhooks/Troubleshooting & Error Playbook

Troubleshooting & Error Playbook

Fast diagnostic steps for common issues across Helix Web, CLI/SDK integrations, and sandbox execution.

HTTP Error Codes Quick Reference

HTTP StatusCauseResolution
401 UnauthorizedMissing, expired, or revoked hx_* bearer tokenConfirm Authorization: Bearer ... header and verify key is active under /developer/keys.
403 principal_escalation_deniedAn 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 deniedInstallation token lacks administration: write or targeted a personal user accountGitHub installation tokens cannot create user-owned repos (create repo manually first) and need administration: write for org repo creation.
429 rate_limit_exceededPer-key RPM/RPD cap or workspace weekly compute window reachedBack off by Retry-After seconds or raise key cap in /developer/keys.
422 / 400 validation_errorMissing goal or malformed JSON schemaInspect 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 .exit status (HELIX_BG_EXIT:<code>) and log tail shown in the tool execution card inside Workspace. Missing .env secrets 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 threadId or runId
PreviousWebhooks, HMAC Verification & ReplayNext Helix Security Architecture
Edit this page on GitHub&nearr;

Platform

How Helix worksSpecialist crewScreens & architectureSecurity & isolationSystem status

Products

Helix WorkspaceAI Staff & Role PacksEmbedded B2B2C StaffPricing & plans

Developers

Developer PlatformDeveloper ConsoleAPI ReferenceSDKs & CLIWebhooks & events

Resources

DocumentationQuickstart guideChangelogHelp Center

Solutions

Use casesCode migrationCVE remediationMulti-cloud ops

Company

About LaunchVerseCareersContact ussupport@launchverse.app

Legal

Privacy PolicyTerms of ServiceExternal status

Social

Sovereign agentic infrastructure engineered in Africa for global engineering teams.

Helix

AI Specialists & Assistants for Everyday Work.

© 2026 LaunchVerse (Helix). All rights reserved.Privacy·Terms·Security·Status