Troubleshoot Execution
Fix runs that cannot reach the target site, offline private runners and tunnel devices, credit gates, and runs stuck in preparing.
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
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 or a private runner.
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:
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.
If it only loads inside your network or VPN, the project needs a tunnel device or a private runner on that network.
For a tunnel, in Settings → Tunnels confirm the device is online and that the project uses it (pinned, or via the Default device).
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.
On the device machine (Node 20+), start the agent again using one of your API keys as the token. Copy the exact command shown in Settings → Tunnels — the same one line works on macOS, Linux, and Windows:
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.
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.
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.
On the runner machine, confirm the runner process is running and restart it if needed.
Confirm it has outbound access to TestVibe (the connection is outbound-only).
Once the runner reconnects, queued runs are picked up automatically. See Private runners.
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 for the failure details once the run reaches a terminal state.
Related Help
Last updated
Was this helpful?