# Troubleshoot runners

Runner problems usually show up as workflows that stay queued, runs that fail during setup, or tests that cannot reach the target site.

Start by checking the selected repository, runner labels, runner status, and target site access.

## Common Issues

| Problem                      | What to check                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| No runners are shown         | Make sure a repository is selected, then refresh the Runners page. Confirm your GitHub permissions and repository access.                  |
| A new runner does not appear | Refresh runners. If it still does not appear, confirm it is registered to the repository or organization and available to this repository. |
| Workflow stays queued        | The selected labels may not match any online runner, or all matching runners may be busy.                                                  |
| Runner is offline            | Start the self-hosted runner service or choose a different runner.                                                                         |
| Runner details look limited  | Your GitHub organization may restrict custom runner metadata. Ask an organization admin to confirm labels and access.                      |
| Site cannot be reached       | Confirm the runner machine can open the target site URL. Use a self-hosted runner for private or VPN-only apps.                            |
| Setup fails before tests run | Check browser dependencies, package installation, secrets, and workflow logs.                                                              |

## Workflow Stays Queued

If a TestVibe workflow remains queued:

1. Open **Settings** > **Runners** in TestVibe.
2. Check which runner is marked as the default.
3. Confirm the **Runs-on labels** match an online runner.
4. Refresh the runner list.
5. If using self-hosted runners, confirm the runner service is running.
6. Try a standard hosted runner such as `ubuntu-latest` if your site is publicly reachable.

Queued workflows usually mean GitHub cannot find available runner capacity that matches the requested labels.

For GitHub's label and group rules, see [Choosing the runner for a job](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job) and [Using self-hosted runners in a workflow](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/use-in-a-workflow).

## Target Site Cannot Be Reached

If the workflow starts but the test cannot open the site:

| Check                 | What to do                                                                     |
| --------------------- | ------------------------------------------------------------------------------ |
| Local URL             | Avoid `localhost` unless the app is running on the runner itself.              |
| Private network       | Use a self-hosted runner that can reach the private environment.               |
| Firewall or allowlist | Allow the runner network path to reach the app.                                |
| Authentication        | Make sure the test instructions and secrets support the required sign-in path. |
| Staging availability  | Confirm the target site is running before starting the test.                   |

## Setup Or Dependency Failures

If the runner starts but fails during setup:

| Check                | What to do                                                           |
| -------------------- | -------------------------------------------------------------------- |
| Browser installation | Confirm Playwright browsers can be installed or are already present. |
| Package restore      | Confirm package lock files and dependency settings are valid.        |
| Secrets              | Confirm required API keys and app credentials are configured.        |
| Operating system     | Choose a runner OS that matches your test or app requirements.       |
| Custom certificates  | Install required certificates on self-hosted runners.                |

## When To Ask An Admin

Ask a GitHub or platform administrator for help when:

| Situation                           | Why admin help may be needed                                  |
| ----------------------------------- | ------------------------------------------------------------- |
| You cannot see organization runners | Access may be limited by organization policy.                 |
| You cannot create a runner          | Repository or organization admin permissions may be required. |
| Runner labels are unclear           | Admins can confirm the exact labels GitHub expects.           |
| Private network access fails        | Network rules, VPN, or firewall settings may need changes.    |

For self-hosted runner health checks, GitHub's [Monitoring and troubleshooting self-hosted runners](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot) page covers status checks and runner application diagnostics.

## Related Help

* [Set the default runner](/runners/set-default-runner.md)
* [Workflow still running or stuck](/troubleshooting/workflow-running-or-stuck.md)
* [Run failed](/troubleshooting/run-failed.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testvibe.com/runners/troubleshooting-runners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.