# Troubleshooting

Use troubleshooting when something blocks the normal TestVibe flow: sign-in, repository selection, AI generation, GitHub Actions runs, or result evidence.

Start with the symptom you can see in TestVibe, then follow the safest recovery steps. Most problems come from one of four places: GitHub access, missing settings, runner availability, or the target site being unavailable from the runner.

## Start Here

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Sign-in problems</strong></td><td>Fix GitHub authorization, browser redirects, and wrong-account issues.</td><td><a href="/pages/o4spiz6apXgIZgmYTh2A">/pages/o4spiz6apXgIZgmYTh2A</a></td></tr><tr><td><strong>Missing repositories</strong></td><td>Check GitHub App installation access, organization selection, and repository permissions.</td><td><a href="/pages/FAsrRSBs3r7qY9lUVvR9">/pages/FAsrRSBs3r7qY9lUVvR9</a></td></tr><tr><td><strong>Missing secrets</strong></td><td>Add the API keys, credentials, or environment secrets needed by generation and runs.</td><td><a href="/pages/dKqKlqKjBn3jRDPit9sQ">/pages/dKqKlqKjBn3jRDPit9sQ</a></td></tr><tr><td><strong>Generation failed</strong></td><td>Recover from failed AI generation by checking keys, site access, instructions, and runners.</td><td><a href="/pages/Vfmalxj2NJhgjqGu9MCN">/pages/Vfmalxj2NJhgjqGu9MCN</a></td></tr><tr><td><strong>Run failed</strong></td><td>Use result evidence to decide whether the app, test, data, or environment failed.</td><td><a href="/pages/2QgfJOf3NN6WVR2bzT9g">/pages/2QgfJOf3NN6WVR2bzT9g</a></td></tr><tr><td><strong>Workflow stuck</strong></td><td>Understand queued, running, finalizing, and stuck GitHub Actions workflow states.</td><td><a href="/pages/3gs6UgqcBcbXFexQsKTo">/pages/3gs6UgqcBcbXFexQsKTo</a></td></tr></tbody></table>

## Safe Recovery Order

When you are not sure what caused the issue, use this order:

1. Refresh the TestVibe status or reopen the affected run, generation, or settings page.
2. Read the visible error message before retrying.
3. Check whether the selected repository, branch, and target site URL are correct.
4. Check required secrets and API keys.
5. Check runner availability if the workflow is queued or never starts.
6. Open GitHub Actions when TestVibe links to a workflow run and you need lower level logs.
7. Retry only after you know what changed.

## Related Setup Pages

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>GitHub App</strong></td><td><a href="/pages/qXffKdzuA8cnIjJrCbPM">Install or update the TestVibe GitHub App.</a></td></tr><tr><td><strong>Repository settings</strong></td><td><a href="/pages/OmsBY1OXulgZoZnkBH4o">Confirm the site URL, source repository, agent, and project settings.</a></td></tr><tr><td><strong>Secrets</strong></td><td><a href="/pages/MI4twczuWahrBFSko238">Add provider keys and test credentials.</a></td></tr><tr><td><strong>Runners</strong></td><td><a href="/pages/U3R2iXfZUFCAHpMySmxw">Fix queued workflows and unreachable sites.</a></td></tr></tbody></table>


---

# 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/troubleshooting.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.