> 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/testvibe-api/guides/diagnose-a-failed-generation.md).

# Diagnose a failed generation

A feature stuck at `failed` almost always means the AI couldn't make the Gherkin's scenarios pass against the real site. The transcript tells you why.

{% stepper %}
{% step %}

### Confirm what happened

```bash
curl -H "Authorization: Bearer $TESTVIBE_API_KEY" \
  "$TESTVIBE_SERVER/api/v1/ops/projects/$PROJECT/features/12/generation"
```

[`get_generation_status`](/testvibe-api/api-reference/generation/get_generation_status.md) shows which section concluded `failure` and when.
{% endstep %}

{% step %}

### Read the transcript

[`get_generation_log`](/testvibe-api/api-reference/generation/get_generation_log.md) returns the per-section log — what the agent explored, what it generated, and what verification said. Look at the section's `statusReason` and final `log` lines first.
{% endstep %}

{% step %}

### Fix the cause

The common failure modes, in order of frequency:

| Symptom in the log                                 | Likely cause                                                          | Fix                                                                                       |
| -------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Couldn't find a page or element the scenario names | Gherkin describes UI that doesn't exist (yet) or names it differently | Reword the scenario to match the real UI, or deploy the feature first.                    |
| Stuck at a login wall                              | The flow needs credentials the agent doesn't have                     | Put test credentials in the scenario (`When I sign in as "user@example.com" / "secret"`). |
| Wrong site explored                                | Project base URL points elsewhere (staging moved?)                    | Pass `siteUrl` on the next generate, or fix the project URL in the app.                   |
| Verification flaky/timeouts                        | Slow environment                                                      | Often passes on retry; consider a calmer test environment.                                |
| {% endstep %}                                      |                                                                       |                                                                                           |

{% step %}

### Update and retry

```bash
testvibe features update 12 --file login.feature
testvibe generate 12 --watch
```

[`update_feature`](/testvibe-api/api-reference/features/update_feature.md) then [`generate_feature`](/testvibe-api/api-reference/generation/generate_feature.md) — each retry is a fresh generation (and fresh credits), so fix the Gherkin before re-rolling.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Doing this from an MCP client? The assistant can run this whole loop itself — see [Your first test from Claude Code](/testvibe-api/guides/first-test-from-claude-code.md).
{% endhint %}


---

# 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:

```
GET https://docs.testvibe.com/testvibe-api/guides/diagnose-a-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.