> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Failure Playbooks

> Error recovery strategies for common MCP tool failures.

When things go wrong, these playbooks help you recover quickly. Each entry includes the error, root cause, and exact recovery steps.

## Error Taxonomy

| HTTP Status | Error Code             | Description                              | Recovery                                  |
| ----------- | ---------------------- | ---------------------------------------- | ----------------------------------------- |
| 400         | `invalid_input`        | Request validation failed                | Check parameter types and required fields |
| 401         | `auth_required`        | OAuth token expired or session invalid   | Reconnect MCP server for fresh OAuth      |
| 403         | `permission_denied`    | Insufficient permissions for this action | Check scopes and trust level              |
| 404         | `entity_not_found`     | Entity doesn't exist or no access        | Search with `orgx_search`                 |
| 409         | `stale_version`        | Concurrent modification conflict         | Re-read entity and retry                  |
| 422         | `hierarchy_incomplete` | Parent has unfinished children           | Complete or cancel children first         |
| 422         | `spawn_blocked`        | Trust or budget insufficient             | Check with `get_my_trust_context`         |
| 422         | `budget_exhausted`     | Autonomous session hit cost limit        | Review `orgx_recommend`                   |
| 422         | `workspace_not_set`    | No active workspace                      | Call `workspace action=set`               |
| 429         | `rate_limit_exceeded`  | Too many requests                        | Wait for `X-RateLimit-Reset`              |
| 500         | `server_error`         | Internal server error                    | Retry with exponential backoff            |

***

## Authentication Errors

### `401 Unauthorized` / `auth_required`

**Cause**: OAuth token expired or session invalid.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "auth_required",
    "message": "OAuth token expired. Reconnect your MCP client to re-authorize.",
    "status": 401
  }
}
```

**Recovery**:

Most MCP clients handle token refresh automatically. If you get a persistent `401`:

1. **Reconnect**: Disconnect and reconnect the MCP server in your client
2. **Re-authorize**: Your browser will open for OAuth sign-in
3. **Retry**: The failed tool call should work after re-auth

If using OpenClaw, click **Disconnect** then re-pair from the dashboard.

<Tip>
  OAuth tokens are refreshed transparently by your MCP client. Persistent 401s
  usually mean the refresh token has expired — just reconnect.
</Tip>

***

## Workspace Errors

### `workspace_not_set`

**Cause**: No active workspace selected for this session.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "workspace_not_set",
    "message": "No active workspace. Call workspace action=set before using this tool.",
    "status": 422
  }
}
```

**Recovery**:

```json theme={"dark"}
// Step 1: List available workspaces
{ "tool": "workspace", "args": { "action": "list" } }

// Step 2: Set the workspace
{ "tool": "workspace", "args": { "action": "set", "workspace_id": "ws_..." } }

// Step 3: Retry original tool call
```

<Info>
  Most tool calls require an active workspace. Call `workspace action=set` early
  in your session.
</Info>

***

## Entity Errors

### `entity_not_found`

**Cause**: The entity ID doesn't exist or you don't have access.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "entity_not_found",
    "message": "Entity 'init_abc123' not found or you do not have access.",
    "status": 404
  }
}
```

**Recovery**:

```json theme={"dark"}
// Search for the entity by type
{
  "tool": "orgx_search",
  "args": { "type": "initiative", "status": "active", "limit": 20 }
}
```

Common causes:

* Typo in entity ID
* Entity was deleted or archived
* Entity belongs to a different workspace

### `hierarchy_incomplete`

**Cause**: Attempting to complete an entity with unfinished child work.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "hierarchy_incomplete",
    "message": "Cannot complete initiative 'init_abc123': 3 child workstreams are still in progress.",
    "status": 422,
    "details": {
      "incomplete_children": ["ws_001", "ws_002", "ws_003"]
    }
  }
}
```

**Recovery**:

```json theme={"dark"}
// Step 1: Check what's blocking completion
{
  "tool": "orgx_act",
  "args": {
    "dry_run": true,
    "type": "initiative",
    "id": "init_..."
  }
}

// Step 2: If blockers exist, resolve them first
// - Complete or cancel child tasks/workstreams
// - Or force complete:
{
  "tool": "orgx_act",
  "args": {
    "type": "initiative",
    "id": "init_...",
    "action": "complete",
    "force": true
  }
}
```

<Warning>
  Using `force: true` skips hierarchy verification. Only use when you're sure
  incomplete children are acceptable.
</Warning>

### `stale_version`

**Cause**: Another process modified the entity between your read and write.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "stale_version",
    "message": "Entity 'task_xyz' was modified by another process. Re-read and retry.",
    "status": 409,
    "details": {
      "current_version": 5,
      "your_version": 3
    }
  }
}
```

**Recovery**:

1. Re-read the entity with `orgx_search` (with `id` parameter)
2. Apply your changes to the fresh data
3. Retry the update

***

## Agent Errors

### `spawn_blocked`

**Cause**: Trust level insufficient for the requested action, or budget exhausted.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "spawn_blocked",
    "message": "Trust level 'supervised' is insufficient for autonomous spawn. Required: 'trusted'.",
    "status": 422,
    "details": {
      "current_trust": "supervised",
      "required_trust": "trusted"
    }
  }
}
```

**Recovery**:

```json theme={"dark"}
// Check trust context
{
  "tool": "get_my_trust_context",
  "args": { "workspace_id": "ws_...", "agent_type": "engineering-agent" }
}
```

If trust is insufficient:

* Escalate to a human for approval
* Use `orgx_spawn` to understand what's needed
* Build trust by completing supervised tasks first

### `budget_exhausted`

**Cause**: Autonomous session hit its `max_cost_usd` limit.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "budget_exhausted",
    "message": "Autonomous session exceeded max_cost_usd ($5.00). Session terminated.",
    "status": 422,
    "details": {
      "max_cost_usd": 5.0,
      "actual_cost_usd": 5.03
    }
  }
}
```

**Recovery**:

* Review the morning brief: `orgx_recommend`
* Start a new session with adjusted budget if needed
* The hard stop is intentional — no overspend is possible

***

## Rate Limiting

### `429 Too Many Requests`

**Cause**: Exceeded rate limits.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for write operations. Retry after 1700000060.",
    "status": 429,
    "details": {
      "limit": 30,
      "window": "1m",
      "reset_at": 1700000060
    }
  }
}
```

| Operation Type   | Limit   | Window |
| ---------------- | ------- | ------ |
| Read operations  | 100 req | 1 min  |
| Write operations | 30 req  | 1 min  |
| Agent operations | 10 req  | 1 min  |

**Recovery**:

Check response headers:

```
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000060
```

Wait until `X-RateLimit-Reset` timestamp, then retry. For batch operations, use
`batch_create_entities` instead of multiple `orgx_write` calls.

***

## Permission Errors

### `403 permission_denied`

**Cause**: The authenticated user does not have the required scopes or role for this action.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "permission_denied",
    "message": "Insufficient permissions. Required scope: 'entities:write'.",
    "status": 403,
    "details": {
      "required_scope": "entities:write",
      "your_scopes": ["entities:read", "workspace:read"]
    }
  }
}
```

**Recovery**:

1. Check your current scopes via your MCP client or the `get_my_trust_context` tool
2. Disconnect and reconnect the MCP server, selecting broader scopes during OAuth
3. If using a tool profile, verify the profile grants the required permissions
4. Ask a workspace admin to elevate your role if needed

***

## Validation Errors

### `400 invalid_input`

**Cause**: Request validation failed due to missing or malformed fields.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "invalid_input",
    "message": "Validation failed: 2 errors.",
    "status": 400,
    "details": {
      "errors": [
        { "field": "title", "message": "Required field is missing." },
        {
          "field": "type",
          "message": "Must be one of: initiative, workstream, task."
        }
      ]
    }
  }
}
```

**Recovery**:

1. Read the `details.errors` array to identify which fields failed validation
2. Correct the parameter types and values -- refer to the tool catalog for expected schemas
3. Ensure all required fields are present before retrying

***

## Internal Errors

### `500 server_error`

**Cause**: An unexpected internal error occurred on the server.

**Example response**:

```json theme={"dark"}
{
  "error": {
    "code": "server_error",
    "message": "Internal server error. Please reference request_id when contacting support.",
    "status": 500,
    "request_id": "req_8f3a2b1c"
  }
}
```

**Recovery**:

1. Retry the request after a short delay (start with 1 second, use exponential backoff)
2. If the error persists after 3 retries, note the `request_id` from the response
3. Contact support with the `request_id` for investigation
4. Check the [Orgx status page](https://status.useorgx.com) for any ongoing incidents

***

## Connection Issues

### MCP connection refused

**Checklist**:

1. Verify the hosted MCP URL is `https://mcp.useorgx.com/mcp` for normal client setup
2. Use `https://mcp.useorgx.com/sse` only if your client explicitly asks for legacy SSE
3. Verify network access to `mcp.useorgx.com`
4. Reconnect to trigger fresh OAuth flow
5. Check that `npx mcp-remote` is installed and up to date

### Tools not appearing after config change

1. Restart your IDE completely (not just reload)
2. Verify `mcp.json` has valid JSON syntax
3. Check that the `args` array is correctly formatted
4. If using a profile, verify the profile name: `?profile=memory` or `?profile=commander`

### Realtime voice connect fails

1. Confirm the browser has microphone permission for `useorgx.com`
2. Start the connection from a user gesture, such as clicking **Connect**
3. Sign in to an OrgX workspace before retrying; the app uses short-lived realtime session credentials
4. If realtime remains unavailable, continue with text input and capture the request ID for support

### Linear or billing actions fail

1. For Linear auth errors, reconnect Linear from **Settings → Integrations**
2. Retry the original action after the reconnect completes
3. For Stripe checkout or billing portal errors, retry once and contact support with the request ID if it persists

***

## Quick Reference

| Error Code             | First Action    | Tool to Use               |
| ---------------------- | --------------- | ------------------------- |
| `401`                  | Reconnect MCP   | Reconnect MCP server      |
| `workspace_not_set`    | Set workspace   | `workspace action=set`    |
| `entity_not_found`     | Search entities | `orgx_search`             |
| `hierarchy_incomplete` | Check children  | `orgx_act dry_run=true`   |
| `spawn_blocked`        | Check trust     | `get_my_trust_context`    |
| `429`                  | Wait + retry    | Check `X-RateLimit-Reset` |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent Quickstart" icon="rocket" href="/docs/agent-ops/agent-quickstart">
    Start from scratch with a working connection.
  </Card>

  <Card title="Tool Profiles" icon="users" href="/docs/agent-ops/tool-profiles">
    Reduce surface area and token usage.
  </Card>
</CardGroup>