> 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.md).

# Troubleshooting

Solve common problems by symptom. Follow the quick checklist first.

### Quick checklist (2 min)

1. Reload the page and try again.
2. Test in an incognito window (no extensions).
3. Disable adblock/privacy extensions for the domain.
4. Confirm permissions and the correct environment (Dev/Staging/Prod).

### Choose the topic

<table data-view="cards"><thead><tr><th>Topic</th><th data-card-target data-type="content-ref">Open</th></tr></thead><tbody><tr><td><strong>AI generation failures</strong><br>Generation doesn't start, freezes, or delivers inconsistent results.</td><td><a href="https://docs.madrix.dev/troubleshooting/deploy-issues.md">Deploy issues</a></td></tr><tr><td><strong>Deployment issues</strong><br>Deployment failing, stuck, or app down after publishing.</td><td><a href="https://docs.madrix.dev/troubleshooting/ai-generation-failures.md">AI generation failures</a></td></tr><tr><td><strong>SSO and login</strong><br>Login looping, callback error, or access denied after authenticating.</td><td><a href="https://docs.madrix.dev/troubleshooting/sso-and-login.md">SSO and login</a></td></tr><tr><td><strong>Performance and slowness</strong><br>Slow UI, slow endpoints, or timeouts.</td><td><a href="https://docs.madrix.dev/troubleshooting/performance-and-slowness.md">Performance and slowness</a></td></tr><tr><td><strong>Database, migrations and schema</strong><br>Migration fails, divergent schema, or connection error.</td><td><a href="https://docs.madrix.dev/troubleshooting/database-migrations-and-schema.md">Database, migrations and schema</a></td></tr></tbody></table>

### How to escalate (open a ticket)

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 %}
