> For the complete documentation index, see [llms.txt](https://docs.madrix.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.madrix.dev/troubleshooting/ai-generation-failures.md).

# AI generation failures

When generation doesn't start, freezes, or delivers inconsistent results.

### When to use

* Generation does not start after sending the prompt.
* Generation keeps “running” for a long time.
* The result comes back incomplete or inconsistent with the prompt.

### Quick checklist (2 min)

1. Simplify the prompt. Make a minimal version.
2. Generate again. Avoid multiple parallel submissions.
3. Reload the page. Try an incognito window.
4. Disable adblock/privacy extensions for the domain.

### Diagnosis

#### 1) Is what you asked for “executable”?

* The prompt has **goal**, **modules/entities**, and **minimal screens**.
* Avoid ambiguity: “a complete system” without scope explodes cost and time.

#### 2) Is the error network/UI related?

* Open the browser Console.
* Check if there is a failing request (401/403/429/5xx).

#### 3) Is the error capacity/limit related?

* If there is a “rate limit”, wait a few minutes and try again.
* Avoid giant prompts. Break them into steps.

### How to resolve (patterns)

* **Gets stuck halfway**: reduce the scope and generate in increments.
* **Poor specification**: force structure with sections and bullets.
* **Result missing parts**: ask for only 1 thing at a time (“add X”, then “adjust Y”).

### When to escalate

* The same minimal prompt fails 3 times.
* Repeatable 5xx error.
* Generation completes, but the app does not run even in Preview.

Before escalating, gather this evidence. It greatly reduces back-and-forth.

* Project and environment (Dev/Staging/Prod).
* Time of the error (with timezone).
* Steps to reproduce (short and deterministic).
* Full error message (no cropped screenshots).
* Screenshot of the screen (if applicable).
* Browser console (relevant errors and warnings).
* Tab **Network** (request that failed + status + payload, if there is no sensitive data).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}