# Troubleshoot failed generation

Generation can fail because of setup, repository access, runner availability, site behavior, or unclear test intent.

Start with the failure details in TestVibe. They usually tell you whether to fix configuration, the target site, or the feature instructions.

## Common Causes

| Cause                       | What to check                                                                 |
| --------------------------- | ----------------------------------------------------------------------------- |
| Missing API key             | Confirm the selected agent has the required repository secret.                |
| Repository permission issue | Confirm the TestVibe GitHub App can write generated files and read workflows. |
| Runner unavailable          | Confirm the selected runner labels match an online runner.                    |
| Site unreachable            | Confirm the target site URL opens from the runner environment.                |
| Login or test data missing  | Add secrets, prerequisites, or clearer setup steps.                           |
| Vague instructions          | Improve Gherkin with visible actions and outcomes.                            |
| App behavior changed        | Update the feature to match the current UI.                                   |

## First Checks

1. Open the failed generation details.
2. Read the summary or failure message.
3. Check whether any output was generated.
4. Confirm the target site URL.
5. Confirm the selected agent and API key.
6. Confirm the runner can start.
7. Decide whether to edit settings, improve Gherkin, or retry.

## Missing API Key

If generation reports a missing provider key:

| Agent family        | Typical secret      |
| ------------------- | ------------------- |
| OpenAI or Codex     | `OPENAI_API_KEY`    |
| Anthropic or Claude | `ANTHROPIC_API_KEY` |

Add or replace the key in repository settings or the Secrets page. See [Add API keys and secrets](/workspace/add-api-keys-and-secrets.md).

## Site Access Problems

If the agent or generated workflow cannot reach the site:

| Check                    | What to do                                                        |
| ------------------------ | ----------------------------------------------------------------- |
| URL                      | Make sure the URL is complete and opens in a browser.             |
| Localhost                | Avoid `localhost` unless the app runs on the same runner machine. |
| Private network          | Use a self-hosted runner with network access.                     |
| Authentication           | Provide test credentials through secrets or clear setup steps.    |
| Environment availability | Confirm staging or QA is running before generation starts.        |

See [Runners](/runners.md) for execution environment setup.

## Repository Or Workflow Problems

If the workflow fails before meaningful generation starts:

| Symptom                | Possible fix                                                     |
| ---------------------- | ---------------------------------------------------------------- |
| Cannot write files     | Check GitHub App access and repository permissions.              |
| Workflow stays queued  | Check runner labels and availability.                            |
| Secrets unavailable    | Confirm secrets are created at repository or organization scope. |
| Generated path missing | Review workflow failure details and repository branch access.    |

For repository access, see [Install the TestVibe GitHub App](/workspace/install-github-app.md).

## Feature Clarity Problems

If generation completes but the output is poor, treat it as an instruction problem.

Improve the feature by adding:

* a clear starting page
* visible UI labels
* required test data
* expected messages or page changes
* one focused behavior per scenario
* stronger `Then` assertions

Then regenerate. See [Write good test instructions](/create-tests/write-good-test-instructions.md).

## Retry Or Regenerate?

| Situation                         | Best next step                                             |
| --------------------------------- | ---------------------------------------------------------- |
| Temporary runner or network issue | Retry after the environment is healthy.                    |
| Missing key or permission         | Fix setup, then regenerate.                                |
| Vague or wrong output             | Edit Gherkin, then regenerate.                             |
| Partial output exists             | Review it before deciding what to keep.                    |
| App is broken                     | Fix the application or target environment before retrying. |

## Related Help

* [Review generation progress](/ai-generation/review-generation-progress.md)
* [Regenerate a test](/ai-generation/regenerate-test.md)
* [Missing secrets](/troubleshooting/missing-secrets.md)
* [Troubleshoot runners](/runners/troubleshooting-runners.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/ai-generation/troubleshoot-failed-generation.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.