Troubleshoot Agent Studio

Use the response status and structured error body to distinguish authentication, permission, input, payload, resource, and server failures. Start with the least invasive check, change one condition at a time, and never include credentials or sensitive workflow data in collected diagnostics.

Collect safe diagnostics

For an API failure, record the request method and path, HTTP status, response code, response error, and any fields keys. Also record whether the caller used a Clerk session or an API key. Redact cookies, authorization headers, API keys, vault values, prompts containing private data, and complete request bodies.

Shared Agent Studio handlers use this error shape:

{
  "success": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "fields": {
    "name": ["Required"]
  }
}

The fields member appears for validation issues and identifies the rejected input paths.

Choose the next check

Use this table only when the affected endpoint returns the listed shared status or code.

Authentication fails with 401

Cause: The route requires a Clerk session and none is active, or an API-key-aware route received a missing, invalid, or expired key.

Check: Identify the route's documented authentication method and the credential type actually sent. Do not assume that an API key works on every API route.

Fix: Sign in again for a session route. For a documented API-key route, send a current key through the supported header and remove any stale credential that could take priority.

Verify: Repeat the same read-only request. Success or a more specific non-401 response confirms that authentication progressed. See Authentication and authorization model.

Access fails with 403

Cause: The caller is known but lacks access to the organization or resource, the required skill permission, or an API-key scope.

Check: Compare the target organization and resource owner with the caller. For skills, identify whether the operation needs viewer, executor, editor, or administrator access. For an API key, inspect its assigned organization and scopes without displaying the key value.

Fix: Ask an authorized administrator to grant the minimum role, skill permission, or scope required for the task. Do not bypass the check or replace the request with an owner credential as a permanent workaround.

Verify: Repeat the original operation and confirm that it completes without FORBIDDEN. Use Manage roles and permissions or Configure skill permissions for the relevant boundary.

A resource returns 404

Cause: The supplied identifier does not resolve, the resource was removed, or the operation cannot locate it in the expected scope.

Check: Obtain the identifier again from a current list response or the relevant Agent Studio screen. Confirm that the organization context matches the resource.

Fix: Replace the stale identifier with the current one. If the item is absent, create or select the intended resource through its documented workflow rather than guessing an ID.

Verify: Fetch the resource first, then repeat the dependent operation. This applies to graphs, executions, MCP servers, RAG documents, marketplace items, vault entries, and schedules only when their endpoint reports NOT_FOUND.

Graph input fails validation

Cause: A graph has no nodes, lacks a START or END terminal, or contains an edge whose source or target does not name an existing node.

Check: Inspect the VALIDATION_ERROR field paths and compare the graph with Graph nodes and validation reference.

Fix: Add the missing terminal, remove the invalid edge, or change its endpoint to an existing node ID. Submit the corrected graph without changing unrelated nodes.

Verify: Save or validate the graph again and confirm that the operation no longer returns 400.

JSON input returns 400

Cause: The request body is malformed JSON, has an invalid Content-Length, or contains a value rejected by the route schema.

Check: Parse the body locally with a JSON-aware editor, verify Content-Type: application/json, and use fields when the response code is VALIDATION_ERROR.

Fix: Correct JSON syntax or the named values. If the error says Invalid Content-Length header, let the HTTP client calculate the header instead of setting it manually.

Verify: Repeat the request and confirm a success response or the workflow's documented next state.

A request returns 413

Cause: The declared request size exceeds the limit used by that route. The shared parser defaults to 1 MB, but a route can set another maximum; the error message reports the actual allowed size.

Check: Read the maximum from Request body too large (...). Maximum allowed is ... and compare it with the request's declared size.

Fix: Remove unnecessary fields or split content using the workflow's supported unit—for example, ingest documents separately instead of combining unrelated content. Do not alter Content-Length to disguise the real size.

Verify: Resend the smaller request and confirm that PAYLOAD_TOO_LARGE no longer appears. For knowledge workflows, continue with Ingest text and files.

The API returns 500

Cause: The server encountered an unexpected error. The client receives INTERNAL_ERROR; database details, stack traces, and internal paths are deliberately omitted.

Check: Confirm process liveness at /api/health, then correlate the request time and path with server-side logs. Treat an ok health response as process evidence, not proof that the affected dependency works.

Fix: Correct the configuration or dependency failure identified in server logs. Preserve the sanitized status, code, path, and timing if another administrator must investigate.

Verify: Repeat the smallest read-only request that reproduced the failure and confirm the expected response. Use Monitor service health for the signal boundary.

Route workflow-specific failures

After resolving the shared HTTP error, continue with the guide for the affected surface:

• execution and approval recovery: Recover and export executions and Review and cancel approval requests
• MCP connectivity: Connect and test MCP tools
• RAG ingestion and search: Ingest text and files and Search and answer from knowledge
• marketplace installation: Use the workflow marketplace
• vault configuration: Manage configuration secrets
• scheduled workflows: Schedule a workflow with cron

If the failure remains, retain only redacted diagnostic fields and the smallest reproducible request shape. Do not export or share secrets, session data, or private source content.