From cd47c73e16fc8337b3c6d7a30b7194512b7849e4 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 27 May 2026 22:50:07 +0000 Subject: [PATCH 1/3] docs: add error pages for infrastructure_timeout and agent_process_failed These two platform error codes are defined in warp-server's platformerrors.go but had no corresponding documentation on docs.warp.dev. Add pages following the existing conventions: - agent-process-failed.mdx: agent process exited unexpectedly during task execution (HTTP 500, not retryable, ERROR state) - infrastructure-timeout.mdx: task forcibly terminated after exceeding the maximum allowed runtime (HTTP 500, not retryable, ERROR state) Wire the pages into: - The Errors sidebar group (src/sidebar.ts) - The Platform errors list on the Errors overview index - vercel.json redirects mapping the underscore form to the hyphen form (both with and without trailing slash), matching the pattern used by every other error code Co-Authored-By: Oz --- .../errors/agent-process-failed.mdx | 62 +++++++++++++++++++ .../troubleshooting/errors/index.mdx | 2 + .../errors/infrastructure-timeout.mdx | 62 +++++++++++++++++++ src/sidebar.ts | 2 + vercel.json | 20 ++++++ 5 files changed, 148 insertions(+) create mode 100644 src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx create mode 100644 src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx 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..9d586f3e --- /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 with an unexpected failure during task execution. + +:::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 indicates a failure during environment setup steps configured by the caller. `agent_process_failed` indicates a failure 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 unexpectedly with a non-zero exit code after environment setup has completed +* An unrecoverable runtime error occurs inside the agent process during task execution +* The agent process is killed by the operating system (for example, due to an out-of-memory condition) + +--- + +## 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, check whether the task prompt or environment configuration is causing the agent to crash. +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..a0eb89d0 --- /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 task is forcibly terminated by the platform after remaining in a non-terminal state past the maximum allowed task age. + +:::note +This is classified as a **platform error** (task state → ERROR) rather than a user error, because the timeout is enforced by Warp's infrastructure rather than by the task's own logic. +::: + +--- + +## Details + +* **HTTP Status:** `500 Internal Server Error` +* **Retryable:** No +* **Task State:** ERROR + +--- + +## When does this occur? + +This error is returned when: + +* A task runs for longer than the platform's maximum allowed task age and is terminated by the periodic stale-task cleanup job +* The agent process did not complete or report a terminal status within the allowed time window +* A networking or infrastructure issue caused 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 the task regularly times out, consider breaking it into smaller, shorter-running subtasks. +2. Review the [environment configuration](/agent-platform/cloud-agents/environments/) for resource allocation or networking issues that could be causing the task to stall. +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/", From a9a36f0941b21902564e2afc0ddf5cd3b6ef99c6 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Wed, 27 May 2026 22:54:00 +0000 Subject: [PATCH 2/3] docs: refine wording on new error pages Audit pass following the existing error pages and the docs style guide: - infrastructure_timeout: simplify the lead sentence, make the platform-vs-user-error callout less circular, add a concrete example for what 'task did not report a terminal status' looks like, and tighten the 'How to resolve' steps with specific things to look for in the environment configuration. - agent_process_failed: clarify that this fires after environment setup has completed (so the distinction from environment_setup_failed is obvious from the lead), spell out which environment-setup steps the other error covers, and replace the vague 'check whether the prompt or environment is causing the agent to crash' with concrete triggers (large prompts, memory-heavy tools, degraded environment). Also confirmed coverage is now 1:1 with platformerrors.go: all 18 ErrorCode constants have a matching .mdx page in the errors directory. Co-Authored-By: Oz --- .../errors/agent-process-failed.mdx | 12 ++++++------ .../errors/infrastructure-timeout.mdx | 14 +++++++------- 2 files changed, 13 insertions(+), 13 deletions(-) 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 index 9d586f3e..a2af0e20 100644 --- 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 @@ -5,10 +5,10 @@ description: >- or contact support if it recurs consistently. --- -The `agent_process_failed` error occurs when the agent process exits with an unexpected failure during task execution. +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 indicates a failure during environment setup steps configured by the caller. `agent_process_failed` indicates a failure during the agent's active execution phase. +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. ::: --- @@ -25,9 +25,9 @@ This is classified as a **platform error** (task state → ERROR) rather than a This error is returned when: -* The agent process exits unexpectedly with a non-zero exit code after environment setup has completed -* An unrecoverable runtime error occurs inside the agent process during task execution -* The agent process is killed by the operating system (for example, due to an out-of-memory condition) +* 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) --- @@ -50,7 +50,7 @@ This error is returned when: ## How to resolve 1. Retry the task. Occasional process failures are transient. -2. If the error recurs consistently, check whether the task prompt or environment configuration is causing the agent to crash. +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. --- 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 index a0eb89d0..07e3cf7b 100644 --- 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 @@ -5,10 +5,10 @@ description: >- allowed runtime. Retry the task or contact support if it persists. --- -The `infrastructure_timeout` error occurs when a task is forcibly terminated by the platform after remaining in a non-terminal state past the maximum allowed task age. +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 timeout is enforced by Warp's infrastructure rather than by the task's own logic. +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. ::: --- @@ -25,9 +25,9 @@ This is classified as a **platform error** (task state → ERROR) rather than a This error is returned when: -* A task runs for longer than the platform's maximum allowed task age and is terminated by the periodic stale-task cleanup job -* The agent process did not complete or report a terminal status within the allowed time window -* A networking or infrastructure issue caused the task to stall silently without reporting completion +* 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 --- @@ -49,8 +49,8 @@ This error is returned when: ## How to resolve -1. Retry the task. If the task regularly times out, consider breaking it into smaller, shorter-running subtasks. -2. Review the [environment configuration](/agent-platform/cloud-agents/environments/) for resource allocation or networking issues that could be causing the task to stall. +1. Retry the task. If it regularly times out, break the work into smaller, shorter-running subtasks or scope the prompt down. +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. --- From 00044e9bc83a3f3e9ddfbecdecf6cf575231639f Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 28 May 2026 10:01:32 -0600 Subject: [PATCH 3/3] Apply suggestion from @rachaelrenk --- .../troubleshooting/errors/infrastructure-timeout.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 07e3cf7b..41d25a90 100644 --- 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 @@ -49,7 +49,7 @@ This error is returned when: ## How to resolve -1. Retry the task. If it regularly times out, break the work into smaller, shorter-running subtasks or scope the prompt down. +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.