diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx new file mode 100644 index 00000000..a2af0e20 --- /dev/null +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx @@ -0,0 +1,62 @@ +--- +title: agent_process_failed +description: >- + The agent process exited unexpectedly during task execution. Retry the task + or contact support if it recurs consistently. +--- + +The `agent_process_failed` error occurs when the agent process exits unexpectedly after environment setup has completed, before the task reaches a normal terminal state. + +:::note +This is classified as a **platform error** (task state → ERROR) rather than a user error. It differs from [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/), which covers failures that happen while initializing the environment (cloning the repo, running setup commands, starting MCP servers). `agent_process_failed` covers failures that happen during the agent's active execution phase. +::: + +--- + +## Details + +* **HTTP Status:** `500 Internal Server Error` +* **Retryable:** No +* **Task State:** ERROR + +--- + +## When does this occur? + +This error is returned when: + +* The agent process exits with a non-zero exit code after environment setup has completed +* An unrecoverable runtime error occurs inside the agent process while it is handling the task +* The agent process is terminated by the operating system (for example, due to an out-of-memory kill or a segmentation fault) + +--- + +## Example response + +```json +{ + "type": "/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/", + "title": "The agent process exited unexpectedly.", + "status": 500, + "instance": "/api/v1/agent/tasks", + "error": "The agent process exited unexpectedly.", + "retryable": false, + "trace_id": "abc123..." +} +``` + +--- + +## How to resolve + +1. Retry the task. Occasional process failures are transient. +2. If the error recurs consistently, look for triggers in the task itself: very large prompts or attached context, memory-heavy tools spawned by the agent, or setup steps that leave the environment in a degraded state. +3. Contact [Warp support](/support-and-community/troubleshooting-and-support/sending-us-feedback/) and include the `trace_id` from the error response if the issue persists. + +--- + +## Related + +* [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — How cloud agent tasks work +* [environment_setup_failed](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Errors during environment setup +* [internal_error](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Catch-all for unexpected server-side errors diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx index 348dab0d..74640b83 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx @@ -73,6 +73,8 @@ These indicate a Warp-side issue. When a cloud agent task encounters a platform * [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) — Invalid or expired API key * [`resource_unavailable`](/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/) — Transient infrastructure issue (retryable) * [`internal_error`](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Unexpected server-side error (retryable) +* [`infrastructure_timeout`](/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/) — Task terminated after exceeding the maximum allowed runtime +* [`agent_process_failed`](/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/) — Agent process exited unexpectedly during task execution --- diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx new file mode 100644 index 00000000..41d25a90 --- /dev/null +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx @@ -0,0 +1,62 @@ +--- +title: infrastructure_timeout +description: >- + The task was forcibly terminated because it remained active past the maximum + allowed runtime. Retry the task or contact support if it persists. +--- + +The `infrastructure_timeout` error occurs when a cloud agent task runs past the platform's maximum allowed runtime and is forcibly terminated. + +:::note +This is classified as a **platform error** (task state → ERROR) rather than a user error, because the termination is performed by Warp's infrastructure rather than by the task itself. +::: + +--- + +## Details + +* **HTTP Status:** `500 Internal Server Error` +* **Retryable:** No +* **Task State:** ERROR + +--- + +## When does this occur? + +This error is returned when: + +* The task runs longer than the platform's maximum allowed runtime and is terminated by the periodic stale-task cleanup job +* The agent process never reports a terminal status within that window (for example, the process is hung or stuck on a long-running command) +* A networking or infrastructure issue causes the task to stall silently without reporting completion + +--- + +## Example response + +```json +{ + "type": "/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", + "title": "The task exceeded the maximum allowed runtime and was terminated.", + "status": 500, + "instance": "/api/v1/agent/tasks", + "error": "The task exceeded the maximum allowed runtime and was terminated.", + "retryable": false, + "trace_id": "abc123..." +} +``` + +--- + +## How to resolve + +1. Retry the task. If it consistently times out, break the work into smaller, shorter-running subtasks or reduce the scope of the prompt. +2. Review the [environment configuration](/agent-platform/cloud-agents/environments/) for setup commands or MCP servers that block on user input, long downloads, or unresponsive network calls. +3. Contact [Warp support](/support-and-community/troubleshooting-and-support/sending-us-feedback/) and include the `trace_id` from the error response if the issue persists. + +--- + +## Related + +* [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — How cloud agent tasks work +* [internal_error](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Other platform-level errors +* [Cloud Agents FAQs](/agent-platform/cloud-agents/faqs/) — Common questions about cloud agents diff --git a/src/sidebar.ts b/src/sidebar.ts index f873bdb6..2f0ece73 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -480,6 +480,8 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ 'reference/api-and-sdk/troubleshooting/errors/authentication-required', 'reference/api-and-sdk/troubleshooting/errors/resource-unavailable', 'reference/api-and-sdk/troubleshooting/errors/internal-error', + 'reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout', + 'reference/api-and-sdk/troubleshooting/errors/agent-process-failed', ], }, ], diff --git a/vercel.json b/vercel.json index 5bd1ddd1..6fedacff 100644 --- a/vercel.json +++ b/vercel.json @@ -2488,11 +2488,21 @@ "destination": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", "statusCode": 308 }, + { + "source": "/reference/api-and-sdk/troubleshooting/errors/agent_process_failed", + "destination": "/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/", + "statusCode": 308 + }, { "source": "/reference/api-and-sdk/troubleshooting/errors/feature_not_available", "destination": "/reference/api-and-sdk/troubleshooting/errors/feature-not-available/", "statusCode": 308 }, + { + "source": "/reference/api-and-sdk/troubleshooting/errors/infrastructure_timeout", + "destination": "/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", + "statusCode": 308 + }, { "source": "/reference/api-and-sdk/troubleshooting/errors/insufficient_credits", "destination": "/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/", @@ -6538,11 +6548,21 @@ "destination": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", "statusCode": 308 }, + { + "source": "/reference/api-and-sdk/troubleshooting/errors/agent_process_failed/", + "destination": "/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/", + "statusCode": 308 + }, { "source": "/reference/api-and-sdk/troubleshooting/errors/feature_not_available/", "destination": "/reference/api-and-sdk/troubleshooting/errors/feature-not-available/", "statusCode": 308 }, + { + "source": "/reference/api-and-sdk/troubleshooting/errors/infrastructure_timeout/", + "destination": "/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", + "statusCode": 308 + }, { "source": "/reference/api-and-sdk/troubleshooting/errors/insufficient_credits/", "destination": "/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/",