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.

These are MCP tool error codes. The REST v1 surface uses a different vocabulary (validation_failed, unauthorized, forbidden, not_found, conflict, rate_limited, internal_error) — see Errors for that set and a condition-by-condition crosswalk. The two are not aliases; do not map one onto the other in client code.

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	Caller cannot act on this record	Check workspace membership 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:

{
  "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.

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

---

Workspace Errors

workspace_not_set

Cause: No active workspace selected for this session.

Example response:

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

Recovery:

// 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

Most tool calls require an active workspace. Call workspace action=set early in your session.

---

Entity Errors

entity_not_found

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

Example response:

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

Recovery:

// 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:

{
  "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:

// 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
  }
}

Using force: true skips hierarchy verification. Only use when you’re sure incomplete children are acceptable.

stale_version

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

Example response:

{
  "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:

{
  "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:

// 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: The accumulated cost of an autonomous session reached its max_cost_usd limit, so no further work was dispatched.

Example response:

{
  "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
    }
  }
}

Note the example: actual_cost_usd is above max_cost_usd. That is expected, not a reporting bug. The cap is evaluated at accounting boundaries — before dispatch against a priced estimate, and between work items against accumulated cost — so a step already in flight when the line is crossed runs to completion and bills in full. max_cost_usd bounds what gets started; it does not truncate a step already running.

Recovery:

• Review the morning brief: orgx_recommend
• Start a new session with adjusted budget if needed
• Expect the final figure to land slightly over the cap when the crossing step was already running. The session closes with status budget_exceeded and the overage is raised as a budget_breach decision, so it is reviewable rather than silent
• Set max_cost_usd below the number you actually want to stay under, sized for the cost of one step

---

Rate Limiting

429 Too Many Requests

Cause: Exceeded rate limits.

Example response:

{
  "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 caller is authenticated, but the account behind the connection cannot act on this record — wrong workspace, or a role that does not permit the action.

Example response:

{
  "error": {
    "code": "permission_denied",
    "message": "Caller cannot act on this record in the active workspace.",
    "status": 403
  }
}

Reconnecting with a broader scope set will not clear this. OAuth scopes are recorded at consent and reported back as granted_scopes; they are not compared against a call. Authorization comes from authentication plus workspace membership — see Declared scopes.

Recovery:

1. Confirm the active workspace holds the record: workspace action=get
2. Confirm the signed-in account is a member of that workspace
3. Check the trust level for the action with get_my_trust_context
4. Ask a workspace admin to add the account or elevate its role

---

Validation Errors

400 invalid_input

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

Example response:

{
  "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:

{
  "error": {
    "code": "server_error",
    "message": "Internal server error. Please reference requestId when contacting support.",
    "status": 500,
    "requestId": "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 requestId from the response
3. Contact support with the requestId for investigation
4. Check the Orgx status page 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

Agent Quickstart

Start from scratch with a working connection.

Tool Profiles

Reduce surface area and token usage.