> ## Documentation Index > Fetch the complete documentation index at: https://docs.tester.army/llms.txt > Use this file to discover all available pages before exploring further. # Run Troubleshooting > Diagnose runs that fail or get blocked before reaching a clear verdict - what each error means and how to fix it and retry. 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. ## `completed` with `BLOCKED` The agent could not produce a product verdict because an environment or setup problem stopped the test, or because of an automation limitation. For example, the target environment was down, credentials were missing or rejected, required test data was absent, a project file the step needed was missing, a required action was unsupported on the run's platform, or the agent ran out of actions or time. Blocked runs are not product failures: they are excluded from failure counts and conclude GitHub checks as neutral. The run's `output.blockedReason` carries a `category` (`environment`, `seed_data`, `credentials`, `test_setup`, or `automation`), a plain-language `summary`, and the step `errorCodes` that produced the verdict. Follow the summary and the error-code guidance below to address the blocker. ## Automation capability unsupported `AUTOMATION_CAPABILITY_UNSUPPORTED` means a required action cannot be performed by the available automation tools on the run's platform. The summary identifies the action and missing capability. The run could not test that behavior. Use a platform that supports the required action, or contact TesterArmy about support. Retrying the same setup does not add the missing capability. ## Project file missing `PROJECT_FILE_MISSING` means a step needed a project file that was not available to the run: an `act` step mentions `@filename` but no file with that name is in the project's **Files** tab, or a `files` step's attachment was deleted. On mobile tests, only photos and videos reach the device, so other file types count as missing. Upload the file in the **Files** tab with the exact name the step mentions, or re-attach it to the `files` step, then retry the run. ## Environment unavailable `ENVIRONMENT_UNAVAILABLE` means the target environment was down or unreachable before the tested journey could start: persistent server errors (5xx), a maintenance page, DNS or connection failures, or an app that never loads. Restore the target environment (deploy, restart, or fix the outage), then retry the run. ## Seed data missing `SEED_DATA_MISSING` means a step depends on pre-existing test data (records, fixtures, or account state such as existing orders, subscriptions, or saved items) that does not exist in the environment. It also covers a required third-party integration (payments, email, CRM, calendar) that is disconnected, unconfigured, or in an error state, because the data the step needs can never exist while the connection is broken. Seed the environment with the data the test depends on, connect any integration it requires, then retry the run. ## `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. The failed step summary states the concrete blocker the agent hit (for example an element that never appeared or a control that did not respond). 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. ## Step no conclusion `STEP_NO_CONCLUSION` means the agent stopped without establishing a clear product verdict. This also covers a failure the agent could not classify after being asked to identify a blocker or confirm that the product misbehaved. Review the step summary, then retry the run or make the instruction more explicit. ## 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, environment, or runtime hints; the dashboard uses them to show a suggested fix and documentation link. When every failed step carries a blockable code (setup, configuration, environment, or an agent-owned runtime guard) and no product issue was reported, the run result is `BLOCKED` instead of `FAILED`. | Code | Meaning | Suggested fix | | - | - | - | | `AUTH_CREDENTIAL_UNAVAILABLE` | The 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_INVALID` | The 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_REQUIRED` | The target site is blocked by HTTP Basic Auth before the app loads. | Add HTTP Basic Auth credentials in site protection settings. | | `VERCEL_BYPASS_REQUIRED` | Vercel deployment protection is blocking the preview URL. | Add a Protection Bypass for Automation token for the project. | | `MOBILE_RELEASE_BUILD_REQUIRED` | The uploaded mobile app is a React Native / Expo dev build that needs a Metro dev server. | Upload a [release build with the JS bundle embedded](/mobile/dev-builds). | | `VIEWPORT_RESIZE_UNSUPPORTED` | The step asked the agent to resize the browser, page, screen, window, or viewport mid-run. | Configure the viewport in [test settings](/run/viewport-size). | | `ENVIRONMENT_UNAVAILABLE` | The target environment was down or unreachable before the tested journey could start. | Restore the target environment, then retry. | | `SEED_DATA_MISSING` | A step depends on pre-existing test data that does not exist in the environment. | Seed the environment with the required data, then retry. | | `PROJECT_FILE_MISSING` | A step needed a project file (an `@filename` mention or a `files` attachment) that was not available. | Upload it to the Files tab, or re-attach it to the `files` step. | | `AUTOMATION_CAPABILITY_UNSUPPORTED` | A required action is unsupported by the available tools on the run's platform. | Use a supported platform or contact TesterArmy about support. | | `STEP_TOOL_LIMIT_EXHAUSTED` | One step required too many agent actions before it could finish. | Split the broad step into smaller focused steps. | | `STEP_NO_CONCLUSION` | The agent could not establish a clear product verdict or identify a specific blocker. | Retry the run or make the step more explicit. | If `errorCode` is absent, use the failed step `error` or `summary` as the source of truth. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.