> ## Documentation Index
> Fetch the complete documentation index at: https://hexelstudio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Resolve common issues with authentication, deployment, and execution.
Start here when something isn't working. Each entry below covers a specific symptom, explains the likely cause, and tells you exactly what to check. If your issue isn't listed, see [Support](/docs/support).
## How to read an error response
Different Hexel services return errors in different shapes. Knowing the format helps you parse the problem immediately.
```json theme={"dark"}
{
"error_code": "quota_exceeded",
"message": "Concurrent sandbox limit reached",
"status": 429
}
```
Error codes: `invalid_request` (400), `vm_not_found` / `not_found` / `skill_not_found` (404), `quota_exceeded` (429), `vm_unavailable` / `capacity_exhausted` (503).
```json theme={"dark"}
{
"error": {
"code": "AUTH.PERMISSION_DENIED",
"message": "Insufficient permissions for this resource",
"request_id": "req_abc123xyz"
}
}
```
The `request_id` is unique per call — include it in support tickets. Error codes: `AUTH.REQUIRED` (401), `AUTH.PERMISSION_DENIED` (403), `RESOURCE.NOT_FOUND` (404), `VALIDATION` (400).
```json theme={"dark"}
{
"error_code": "invalid_request",
"message": "fleet_id is required",
"status": 400
}
```
Task streams emit `task.error` and `task.failed` events with the error detail in the event payload.
```json theme={"dark"}
{
"error": {
"code": "PROVIDER_AUTH_FAILED",
"message": "OAuth token for provider expired"
}
}
```
Tool Gateway errors are always `{error: {code, message}}`.
***
## Authentication
**`401 Unauthorized` on every request**
* Confirm your API key or client credentials are correct and not expired.
* Verify the credential is set: `HEXEL_API_KEY`, or `HEXEL_CLIENT_ID` + `HEXEL_CLIENT_SECRET`.
* Access tokens last 15 minutes. If you exchange them manually with curl, re-exchange after expiry. The SDKs refresh automatically.
**`403 Permission Denied`**
* Your credential is valid but lacks the required permission. Check the role assigned to the service user. Permissions follow the pattern `data-platform::` or `orchestrator:task:write`.
**Requests hit the wrong environment**
* Each credential is scoped to a workspace and environment. Use the credential for the environment you intend to operate in.
***
## Compute
**Instance never reaches `Running`**
* Verify your image implements the [agent contract](/docs/compute/agents#agent-contract): `GET /health` returning `{"status": "ok"}` and `GET /.well-known/agent.json`.
* Check [logs](/docs/observability/logs) for startup errors.
* For private registries, confirm pull credentials are correct.
**Deploy command fails**
* Deploy is only available via the REST API (`POST /compute/v1/agents/{agent_id}/instances`) or the `hexel` CLI (`hexel compute instance deploy `). There is no `instance.deploy()` in the SDKs.
**Instance shows `Failed`**
* Inspect logs for the cause, fix the image or configuration, then redeploy with `client.compute.instance.redeploy()` or `hexel compute instance redeploy`.
**`503 capacity_exhausted` on sandbox or instance creation**
* The requested tier has no available capacity. There is no auto-fallback to another tier. Wait and retry, or use a different tier if your workload allows it.
**`429 quota_exceeded` on sandbox allocation**
* You've hit the `ConcurrentSandboxes` limit. Release idle sandboxes or request a quota increase via [Support](/docs/support).
***
## Data Platform
**`RESOURCE.NOT_FOUND` (404)**
* The knowledge store, memory store, or datasource ID does not exist in the current environment. Verify the ID and that your credential targets the correct environment.
**`VALIDATION` (400)**
* A request parameter is invalid (e.g., `chunk_size` out of range, missing required field). Check the error message for the specific field.
**Search returns poor results**
* Tune `chunk_size`, `chunk_overlap`, and `score_threshold`. Keep stores focused on one domain. See [Knowledge Stores](/docs/data-platform/knowledge-stores).
**Connector data is stale**
* Confirm the source has a sync schedule and check [Syncs](/docs/data-platform/syncs) for failed runs.
***
## Orchestration
**Task stuck in `plan_review`**
* The plan needs approval. Review it via [Approvals](/docs/orchestration/approvals); pending approvals expire after 24 hours.
**Task failed unexpectedly**
* Stream or [replay](/docs/orchestration/streaming-and-replay) the task to see where it failed. Task streams emit `task.submitted` → `task.state` → `task.error` → `task.failed` events with the error detail in the payload.
**`429 Too Many Requests` on task submission**
* Orchestration is limited to 100 requests per organization per minute. Batch submissions or implement a queue with backoff.
***
## Tool Gateway
**Tool call fails with an authorization error**
* Confirm the provider account is connected and the agent is [bound](/docs/tool-gateway/bindings) to the toolkit.
* Check that the tool is not excluded by a [workspace group](/docs/tool-gateway/workspace-groups) allow-list.
**Tool execution times out**
* Use asynchronous execution and poll the call result. See [Executing Tools](/docs/tool-gateway/execution).
***
## Getting help faster
If a problem persists after the steps above:
1. Capture the exact error response (including `error_code` and `request_id` where present).
2. Note the `environment_id`, `workspace_id`, and resource identifier (agent, instance, task, sandbox, or store).
3. Check [Logs](/docs/observability/logs) for the failing resource at the time of failure.
4. Reach out through [Support](/docs/support) with those details.
Each error response carries an `error_code` (see the per-feature **Errors** sections: [Compute](/docs/compute/overview#errors), [Orchestration](/docs/orchestration/overview#errors), [Data Platform](/docs/data-platform/overview#errors), [Tool Gateway](/docs/tool-gateway/overview#errors)). Including it speeds up diagnosis.
## Related pages
Credential setup and tokens.
Find the root cause.
SDK retries and errors.
Get more help.