> 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/deploy-issues.md).

# Deploy issues

Deploy failing, stuck, or app down after publishing.

### When to use

* Deploy fails with error.
* Deploy is in progress and doesn't finish.
* Deploy completes, but the application doesn't start.

### Quick checklist (2 min)

1. Confirm the correct environment (Dev/Staging/Prod).
2. Run a new deploy. Avoid 'deploy spam'.
3. Check if there was a recent change to variables/secrets.

### Diagnosis

#### 1) Is the error build or runtime?

* **Build**: fails before publishing artifacts.
* **Runtime**: publishes, but crashes on startup or at endpoints.

#### 2) Environment configuration

* Are required variables set?
* Do integrations (API keys) exist in the correct environment?

#### 3) External dependencies

* Is the database accessible?
* Do webhooks and third-party services respond?

### How to resolve (patterns)

* **Build broke**: review recent changes and revert the last delta.
* **Runtime crashed**: check app logs and startup failure.
* **Intermittent error**: confirm limits (rate limit), timeout, and dependencies.

### When to escalate

* 5xx error in the pipeline is repeatable.
* Deploy stuck for more than 20 min.
* App with downtime in Staging/Prod.

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