diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx index 406583c6..3afc8ccf 100644 --- a/src/content/docs/agent-platform/cloud-agents/environments.mdx +++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx @@ -290,12 +290,12 @@ If your setup commands depend on secrets or credentials, configure them through ### Common issues -* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. +* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. Setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). * Solution: Write idempotent setup commands that work on a fresh container. * **Missing credentials or secrets** – Builds fail when private repos, package registries, or external services require authorization. * Solution: Configure credentials with [Agent Secrets](/agent-platform/cloud-agents/secrets/). -* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions. +* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions. Missing external authorization can surface as [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). * Solution: See [Integration setup](/reference/cli/integration-setup/#how-github-authorization-works) for GitHub authorization setup. * **Docker image incompatibility** – You see the error: "VM failed before the agent could run. This is likely an issue with your Docker image." - * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc. + * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc. This can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). * Solution: Switch to a glibc-based image such as Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images (e.g. `node`, `python`, `rust`). diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx index 909c336e..76115bdf 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx @@ -65,6 +65,12 @@ You can specify a skill using the `skill` input parameter, either instead of or warp_api_key: ${{ secrets.WARP_API_KEY }} ``` +:::tip +If the action fails, use the returned error code to narrow the fix. Common errors include: + +* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) (missing, invalid, or expired `warp_api_key` secret) +::: + #### Skill format options The `skill` parameter supports multiple formats for referencing skills: diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx index 58f96de6..d70b96f4 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/index.mdx @@ -13,7 +13,7 @@ Warp integrations let your team trigger agents directly from the terminal, or fr * Run code inside your codebase in a remote environment * Open pull requests and perform other multi-step agent workflows on your behalf -If you're deciding whether an agent should run from a schedule, Slack or Linear, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). +If you're deciding whether an agent should run from a schedule, Slack, Linear, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). :::note For a full walkthrough of Warp's integrations and configurable environments, please refer to [Integration setup](/reference/cli/integration-setup/). @@ -23,86 +23,15 @@ All of this is powered by the [Oz CLI](/reference/cli/). --- -## Quickstart +## Get started -The fastest way to get agents running from Slack or Linear is to create an environment with the guided flow. An **environment** defines everything the agent needs to run your code remotely, including your Docker image, repos, and setup commands. +Use the setup walkthrough below for a quick look at how environments connect to integrations, then choose the guide that matches what you want to do next. -#### 1. Run /create-environment - -From Warp, run the following slash command: - -``` -/create-environment -``` - -You can run it inside any repo, or point it at multiple repos: - -``` -/create-environment ./frontend ./backend -/create-environment your-org/repo-name -/create-environment https://github.com/your-org/api.git -``` - -:::note -Learn more about slash commands and how to use them in the [Slash Commands](/agent-platform/capabilities/slash-commands/) documentation. -::: - -The guided flow will: - -* Detect which repos you want the agent to work with -* Identify languages, frameworks, and tools -* Suggest a Docker image (or build/push one if needed) - * The Docker image can be your own custom image, an official base image (e.g. node, python), or one of Warp's prebuilt dev images (see [repo](https://github.com/warpdotdev/oz-dev-environments)). -* Recommend setup commands -* Create the environment and return an environment ID - -This produces a ready-to-use environment that Warp can use across Slack, Linear, and terminal triggers. - -#### 2. Authorize GitHub - -Warp will prompt you to install or update the Warp GitHub app so the agent can read and write to the repos you included. You only need to do this once. Teammates will authorize on their first run as needed. - -:::note -**Using Azure DevOps, GitLab, or Bitbucket?** Native integrations for these platforms are not yet available, but you can connect repositories by storing a personal access token as a Warp-managed secret and cloning via a setup command. See [Azure DevOps](/agent-platform/cloud-agents/integrations/azure-devops/), [GitLab](/agent-platform/cloud-agents/integrations/gitlab/), or [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/) for step-by-step instructions. -::: - -#### 3. Create an integration - -:::note -For easier setup, use the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev) to configure integrations with a guided flow. The web app works on mobile devices. -::: - -Alternatively, use the CLI: - -For Slack: - -``` -oz integration create slack --environment -``` - -For Linear: - -``` -oz integration create linear --environment -``` - -The CLI opens an authorization page where you install Oz into your Slack workspace or Linear team. - -#### 4. Start using agents - -In Slack: - -* Tag **@Oz** in a message or thread -* Or DM the bot - -In Linear: - -* Tag @Oz on an issue - -Warp will read the thread/issue, spin up your environment, run the workflow in the cloud, and post progress + PRs back into the same conversation. - ---- - -For more details on configuring integrations and environments in Warp, please refer to [Integration setup](/reference/cli/integration-setup/). +* [Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish. +* [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail. +* [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) - Trigger agents from team conversations, issues, and comments. +* [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/) - Run agents from CI workflows and repository events. +* [GitLab](/agent-platform/cloud-agents/integrations/gitlab/), [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/), and [Azure DevOps](/agent-platform/cloud-agents/integrations/azure-devops/) - Connect non-GitHub repositories with tokens and Warp-managed secrets. +* [AWS, GCP, and other cloud providers](/agent-platform/cloud-agents/integrations/cloud-providers/) - Give cloud agents short-lived access to cloud services. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index 3f112fdf..e31a8da0 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -110,6 +110,13 @@ oz integration create linear --environment The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. +:::tip +If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: + +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization) +::: + --- ### Uninstallation instructions @@ -124,7 +131,7 @@ To remove the Oz integration from Linear: -After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. +After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx index 37c0ea76..70253dc5 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx @@ -43,6 +43,13 @@ oz integration create slack --environment Replace `` with your environment ID (see [Environments](/agent-platform/cloud-agents/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace. +:::tip +If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Common errors include: + +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) +::: + To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: ```bash diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index b37d510b..86d3d5c9 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -135,6 +135,13 @@ oz integration create slack --environment The CLI will open a browser window to install the Oz app into your Slack workspace. After installation, the integration becomes available to all members of your Warp team. +:::tip +If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: + +* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) +::: + You can optionally attach a custom prompt that is applied to every agent run: ``` @@ -170,7 +177,7 @@ To remove the Oz app from your Slack workspace: ![Confirmation dialog to remove the Oz app from a Slack workspace.](../../../../../assets/agent-platform/remove-slack-app.png) -Once removed, Slack will immediately disable the integration for all teammates. +Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting diff --git a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx index 9e5773e6..1c8e72e5 100644 --- a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx @@ -90,7 +90,7 @@ Where the agent was launched from. Common sources include: Warp uses a small set of statuses to help you quickly identify what needs attention: -
StatusIconDescription
WorkingN/Ain progress (may include queued / running states)
Blocked🟨

(interactive only)


the conversation is waiting on user input or a required step

Canceled⬜️(interactive only)

the interactive conversation was canceled before completion
Failed / Errored🔺something went wrong (applies to both interactive and cloud agent runs)
Success✅completed successfully (applies to both interactive and cloud agent runs)
+
StatusIconDescription
WorkingN/Ain progress (may include queued / running states)
Blocked🟨

(interactive only)


the conversation is waiting on user input or a required step

Canceled⬜️(interactive only)

the interactive conversation was canceled before completion
Failed / Errored🔺something went wrong (applies to both interactive and cloud agent runs)
Success✅completed successfully (applies to both interactive and cloud agent runs)
**Duration (for cloud agent tasks)** diff --git a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx index 8e7b0d5c..0700dd58 100644 --- a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx @@ -151,13 +151,13 @@ Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatical ## Troubleshooting **Environment creation fails**\ -Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images. +Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error. **Agent can't access repos**\ -Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. +Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `; permission mismatches can surface as [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). **Not enough credits to run cloud agents**\ -Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. +Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). **More resources** diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index f000e7ee..60cbb5c8 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -82,7 +82,7 @@ Your team must meet the following requirements to run integrations: When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits based on who the run is billed to: * **User-triggered runs on Build, Max, or Business** - Warp draws from any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then the user's plan-included credits, then the user's add-on credits. Add-on credits are scoped to the individual user and are not shared across the team. -* **Team API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. +* **Team API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap; once the cap is reached, runs are blocked until the cap resets or increases. * **Enterprise plans** - Runs draw from the team-scoped credit pool, per your Enterprise contract terms. If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run. @@ -197,7 +197,7 @@ Warp’s behavior in GitHub is defined by two layers of control: **In practice, agents can only operate on repositories that:** * Are included in the environment configuration -* Are accessible to both the GitHub app and the triggering user +* Are accessible to both the GitHub app and the triggering user. --- @@ -251,6 +251,16 @@ It's the team's responsibility to manage triggers, confirm they behave as intend --- +## Troubleshooting + +If a cloud agent or integration run fails with an error code, use the error reference to narrow the fix: + +* **Missing GitHub or external authorization** - See [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) when a user needs to authorize GitHub, Slack, or Linear before a run can continue. +* **Insufficient repo permissions** - See [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) when the triggering user or GitHub App lacks access to the repo the agent needs. +* **Credits or spend caps block a run** - See [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) or [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) when the billed account has depleted credits or reached a configured spend cap. + +--- + ## Related resources * [Add-on credits](/support-and-community/plans-and-billing/add-on-credits/) - How user-scoped add-on credits, auto-reload, and the team-wide spend cap work on self-serve plans. diff --git a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx index b41429af..df4501d0 100644 --- a/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx @@ -281,7 +281,7 @@ Each scheduled run behaves like a standard cloud agent run, with a few important * Runs execute automatically without human intervention. * All usage is billed to the team’s shared credit balance. -If a scheduled run fails, it does not block future runs. Each execution is independent. +If a scheduled run fails, it does not block future runs. Each execution is independent. Use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret any returned error code. ### Permissions and responsibility diff --git a/src/content/docs/reference/api-and-sdk/index.mdx b/src/content/docs/reference/api-and-sdk/index.mdx index 152d8643..89f0d09c 100644 --- a/src/content/docs/reference/api-and-sdk/index.mdx +++ b/src/content/docs/reference/api-and-sdk/index.mdx @@ -32,7 +32,7 @@ Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [ * **Typed requests and responses** (editor autocomplete, fewer schema mistakes) * **Built-in retries and timeouts** (with per-request overrides) -* **Consistent error type**s that map to API status codes +* [**Consistent error types**](/reference/api-and-sdk/troubleshooting/errors/) that map to API status codes * **Helpers for raw responses** when you need headers/status or custom parsing If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. @@ -105,7 +105,7 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type Fetch full details for a single run, including session link and resolved configuration. -All endpoint semantics, query parameters, and error codes are documented on the [Agents API Reference](/api). +All endpoint semantics, query parameters, and [error codes](/reference/api-and-sdk/troubleshooting/errors/) are documented on the [Agents API Reference](/api). --- diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index f3472053..71b6ad6f 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -70,7 +70,7 @@ The `state` has the following possible values: * `QUEUED` - The run is waiting to start. * `INPROGRESS` - The agent is actively running. * `SUCCEEDED` - The run completed successfully. -* `FAILED` - The run encountered an error. Check the `status_message` field in the response for details. +* `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret the error code. These are the most common states. See the [full API reference](/reference/api-and-sdk/) for all possible values. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index c9207226..b9651b9b 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -44,7 +44,7 @@ Team keys without GitHub App authorization are the right fit for automated workf Warp supports two types of API keys, each with different billing and identity behavior: * **Personal API keys** - Cloud agent runs authenticate as you, just like running an agent from the Warp app or triggering one via Slack or Linear. On Build, Max, and Business plans, runs draw from your plan-included credits, then your add-on credits — both scoped to your individual user. On Enterprise plans, runs draw from the team-scoped credit pool, per your Enterprise contract terms. -* **Team API keys** - Cloud agent runs are not tied to any individual user. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted (insufficient credits error). With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, team API key runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. +* **Team API keys** - Cloud agent runs are not tied to any individual user. On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap. On Enterprise plans, team API key runs draw from the team-scoped credit pool. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. Team API keys are useful for fully automated workflows, CI/CD pipelines, and scheduled tasks where no specific user context is needed. For the full credit waterfall and how it interacts with add-on credits, see [Access, billing, and identity permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) and [add-on credits](/support-and-community/plans-and-billing/add-on-credits/). @@ -66,7 +66,7 @@ $ oz agent run --api-key "wk-xxx..." --prompt "analyze this codebase" ``` :::note -API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be invalid or from an older format. +API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be [invalid or from an older format](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). ::: ## Managing API keys @@ -88,7 +88,7 @@ To delete an API key: 2. Find the key you want to delete in the API Keys list. 3. Click the delete icon next to the key. -Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access. +Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). ## Best practices diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index 97db4c3a..8aad3139 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -52,6 +52,14 @@ Setting up an integration consists of three steps. 2. **Authorize GitHub** so Warp can clone repositories, write code, debug issues, open pull requests, and more. 3. **Configure** the Oz app with an integration. +:::tip +If setup fails, use the returned error code to narrow the fix. Common errors include: + +* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) (environment initialization issues) +* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or external-service authorization) +* [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) (incomplete integration setup) +::: + --- ## Step 1: Creating an environment diff --git a/src/content/docs/reference/cli/troubleshooting.mdx b/src/content/docs/reference/cli/troubleshooting.mdx index 025b9d80..ea9eabb2 100644 --- a/src/content/docs/reference/cli/troubleshooting.mdx +++ b/src/content/docs/reference/cli/troubleshooting.mdx @@ -34,7 +34,7 @@ oz --version **Authentication issues** * Interactive login: ensure you've completed the browser-based flow with `oz login`. -* API keys: confirm the key is valid, not expired, and exported correctly. +* API keys: confirm the key is valid, not expired, and exported correctly. Invalid, expired, or missing keys can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). **Agent or MCP errors**\ Ensure your agent profile and [MCP servers](/agent-platform/capabilities/mcp/) are configured properly, with correct permissions. See [MCP Servers](/reference/cli/mcp-servers/) and [Agent profiles](/reference/cli/agent-profiles/) for details. @@ -113,7 +113,7 @@ oz environment delete Add `--force` to skip confirmation checks for environments used by integrations. -Only do this once you've confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail until you create a new integration with a valid environment. +Only do this once you've confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail with a [`resource_not_found` error](/reference/api-and-sdk/troubleshooting/errors/resource-not-found/) until you create a new integration with a valid environment. ### Integrations @@ -144,7 +144,7 @@ This happens when: * You add a repo that Warp doesn’t have access to yet, or * You personally haven’t granted the Warp GitHub app permissions for that repo. -Follow the GitHub popup flow to install/adjust the Warp GitHub app. +Follow the GitHub popup flow to install/adjust the Warp GitHub app. Missing external authorization can return an [`external_authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). #### **The agent can’t open PRs or push changes to my repo** @@ -155,7 +155,7 @@ Check the following: 2. **Warp GitHub app has access to that repo** 1. In GitHub’s settings, confirm the Warp app is installed and that the repo is selected. 3. **You have write access** - 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf. + 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf, and the run may return a [`not_authorized` error](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). ### Docker image & environment failures @@ -167,7 +167,7 @@ Check: 2. The image is public on Docker Hub. 3. You can pull it locally: `docker pull ` -If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. +If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. Image pull and setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). #### **The agent can’t find tools or runtimes inside the environment** @@ -178,7 +178,7 @@ This usually means the Docker image is missing required dependencies. Fix by eit #### **I see "VM failed before the agent could run. This is likely an issue with your Docker image"** -This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime. +This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime, and this can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). Fix: