For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Discord
DocsAPI Reference
DocsAPI Reference
  • Get Started
    • Welcome
    • Introduction
    • Quick Start
  • Run
    • Run Videos
    • Run Mode
    • Viewport Size
    • Preparation Test
    • Pull Request Testing
    • Production Monitoring
    • Group Webhooks
    • Run Troubleshooting
  • Auth
    • Test Credentials
    • API Keys
    • Agent Mail Inboxes
    • HTTP Basic Auth
    • Auth Troubleshooting
  • Mobile
    • Overview
    • App Uploads
    • Expo EAS
    • GitHub Actions
  • Integrations
    • Vercel
    • Coolify
    • Custom Infrastructure
    • Slack
    • Discord
  • Guides
    • Testing Staging Environment
  • CLI
    • Getting Started
    • Local Development
    • Agentic Usage
  • AI
    • LLMs
LogoLogo
Discord
On this page
  • completed with FAILED
  • failed
  • Provider session unavailable
  • Run timeout
  • Step tool limit exhausted
  • UI target not found
  • Wrong target URL
  • Agent step error codes
Run

Run Troubleshooting

||View as Markdown|
Was this page helpful?
Edit this page
Previous

Group Webhooks

Next

Test Credentials

Built with

Use this page when a test run stops, times out, or fails before producing a clear product issue.

completed with FAILED

The agent finished the run and found a product, configuration, or test-step issue. Open the run details, review failed steps, screenshots, and reported issues.

failed

The worker or runtime failed before normal completion. Common causes include provider capacity, browser/device startup failures, AI provider interruptions, or invalid run setup.

Provider session unavailable

Browser and device providers can temporarily run out of capacity. Retry the run after a short wait.

Run timeout

If a run times out:

  1. Retry once to rule out transient slowness.
  2. Split long tests into smaller flows.
  3. Make steps more specific so the agent has less ambiguity.
  4. Check whether the target environment is slow or unavailable.

Step tool limit exhausted

STEP_TOOL_LIMIT_EXHAUSTED means one test step required too many agent actions before it could finish. This usually happens when a step combines multiple workflows or assertions.

Split broad steps into smaller focused steps with one intent each.

Instead of:

“Log in, create a project, invite a teammate, run a test, and verify the result.”

Use:

  1. Log in.
  2. Create a project.
  3. Invite a teammate.
  4. Run a test.
  5. Verify the result.

UI target not found

If a failed step says the agent could not find a UI target:

  1. Confirm the element exists in the target environment.
  2. Update the step with clearer user-visible labels.
  3. Check whether the page requires auth or setup before that step.

Wrong target URL

Tests use the run target URL when provided, otherwise the project URL. For PR and staging runs, confirm the webhook, deployment, or dashboard trigger points to the expected URL.

Agent step error codes

API responses can include steps[].errorCode on failed steps. These codes are machine-readable setup, configuration, or runtime hints; the dashboard uses them to show a suggested fix and documentation link.

CodeMeaningSuggested fix
AUTH_CREDENTIAL_UNAVAILABLEThe step needed login/OAuth/provider credentials that were not available to the run.Select or add the project credential required by the login step.
AUTH_CREDENTIAL_INVALIDThe target app rejected the provided credential, such as an incorrect username or password.Confirm the credential works, update the project credential, then retry.
AUTH_BASIC_REQUIREDThe target site is blocked by HTTP Basic Auth before the app loads.Add HTTP Basic Auth credentials in site protection settings.
VERCEL_BYPASS_REQUIREDVercel deployment protection is blocking the preview URL.Add a Protection Bypass for Automation token for the project.
VIEWPORT_RESIZE_UNSUPPORTEDThe step asked the agent to resize the browser, page, screen, window, or viewport mid-run.Configure the viewport in test settings.
STEP_TOOL_LIMIT_EXHAUSTEDOne step required too many agent actions before it could finish.Split the broad step into smaller focused steps.

If errorCode is absent, use the failed step error or summary as the source of truth.