> For the complete documentation index, see [llms.txt](https://docs.testvibe.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.testvibe.com/runners/troubleshooting-runners.md). # Troubleshoot Execution Execution problems usually show up one of a few ways: the test fails because the site cannot be opened, a tunnel device or private runner shows offline, a run is blocked by credits, or a run stays stuck in **preparing**. ## Common Issues | Problem | What to check | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Site cannot be reached from the cloud sandbox | Confirm the URL opens from outside your network. If it is private, switch the project to a [tunnel device](/account-settings/tunnel-devices.md) or a [private runner](/runners/self-hosted-runners.md). | | `localhost` URL fails | The cloud sandbox runs in the cloud, not on your machine. Run `tvtunnel` on the machine hosting the app, or use a private runner there. | | Tunnel device shows offline | The `tvtunnel` agent stopped or the machine is asleep. Restart the agent; a device reads as offline if it hasn't sent a heartbeat recently. | | Private runner not picking up jobs | The runner process stopped or lost outbound access. Restart it and confirm it can reach TestVibe. | | Wrong tunnel device is used | Check the project's pinned device and the **Default** device in **Settings → Tunnels**. | | Run blocked: not enough credits | Runs are gated on credits before they start. Top up in **Settings → Billing** or check **Credit Usage**. | | Run fails on an undefined variable or secret | A test references a `{{var:NAME}}` or `{{secret:NAME}}` that isn't defined. Add it in **Settings → Variables & Secrets**. | | Run stuck in preparing | A sandbox is being allocated (or TestVibe is waiting for an online private runner). Brief waits are normal; if it doesn't progress, cancel and rerun — and confirm the device or runner is online for private apps. | | Test starts but sign-in fails | Confirm credentials in Settings → Variables & Secrets and that the test references them correctly. | | Staging is down | Confirm the target site is actually running before starting the run. | ## Site Cannot Be Reached If the run starts but the test cannot open the site: 1. Open the site URL in a private browser window from a network *outside* your own. If it loads, the cloud sandbox can reach it too. 2. If it only loads inside your network or VPN, the project needs a [tunnel device](/account-settings/tunnel-devices.md) or a [private runner](/runners/self-hosted-runners.md) on that network. 3. For a tunnel, in **Settings → Tunnels** confirm the device is online and that the project uses it (pinned, or via the Default device). 4. Rerun one small test to confirm. ## Tunnel Device Offline A device goes offline when the `tvtunnel` agent stops — the process was closed, the machine rebooted or went to sleep, or outbound network access was lost. A device that stops sending its heartbeat for more than about 90 seconds reads as offline and runs that target a private URL through it will not start. 1. On the device machine (Node 20+), start the agent again using one of your [API keys](/account-settings/api-keys.md) as the token. Copy the exact command shown in **Settings → Tunnels** — the same one line works on macOS, Linux, and Windows: ```bash npx --yes testvibe-tunnel@latest --token --relay --server ``` If the machine can't reach the public npm registry (self-hosted or air-gapped), use the tarball fallback shown in the panel instead — see [Tunnel devices](/account-settings/tunnel-devices.md). 2. Watch **Settings → Tunnels** — the device flips back to online when the agent reconnects. If a run reports the agent is out of date, rerun the command above to update it. 3. For long-term reliability, run the agent as a service on a machine that never sleeps. ## Private Runner Offline If a project runs on a private runner and runs sit in **preparing**, no runner is currently online to pick up the job. 1. On the runner machine, confirm the runner process is running and restart it if needed. 2. Confirm it has outbound access to TestVibe (the connection is outbound-only). 3. Once the runner reconnects, queued runs are picked up automatically. See [Private runners](/runners/self-hosted-runners.md). ## Run Blocked By Credits Runs, generations, and assistant turns are checked against your workspace credit balance before they start. If a run won't start because of credits, top up or upgrade in **Settings → Billing**, and review where credits went in **Settings → Credit Usage**. ## Run Stuck In Preparing **Preparing** means a sandbox is being allocated and set up (or, for a private runner, TestVibe is waiting for an online runner). This normally takes moments. If a run sits there unusually long, cancel it and rerun. If it keeps happening, check [Run failed](/troubleshooting/run-failed.md) for the failure details once the run reaches a terminal state. ## Related Help * [Choose an execution target](/runners/choose-a-runner.md) * [Private runners](/runners/self-hosted-runners.md) * [Tunnel devices](/account-settings/tunnel-devices.md) * [Understand live run status](/run-tests/understand-live-run-status.md) * [Run failed](/troubleshooting/run-failed.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.testvibe.com/runners/troubleshooting-runners.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.