> ## Documentation Index
> Fetch the complete documentation index at: https://help-center-starter-replace-template-content.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling build failures

> What to do when a Mintlify deployment fails.

Build failures prevent your changes from going live. They're usually caused by MDX syntax errors, invalid `docs.json` configuration, or broken component references.

## Find the error

1. Go to **\[Project] → Deployments** in your Mintlify dashboard.
2. Click the failed deployment to open its details.
3. Open the **Build log** tab. The error message near the bottom of the log usually identifies the file and line number causing the failure.

## Common failure causes

<Tabs>
  <Tab title="MDX syntax errors">
    MDX is stricter than Markdown. Common mistakes:

    * Unclosed JSX tags (for example, `<Note>` without `</Note>`)
    * HTML entities that need escaping (use `&amp;` instead of `&`, `&lt;` instead of `<`)
    * Invalid frontmatter YAML (missing quotes around strings with special characters)

    Fix: Find the file and line mentioned in the build log and correct the syntax.
  </Tab>

  <Tab title="docs.json errors">
    Invalid `docs.json` configuration fails the build. Common mistakes:

    * A page listed in navigation that doesn't exist as an `.mdx` file
    * Invalid JSON syntax (trailing commas, missing quotes)
    * A required field missing (`name`, `theme`, `colors.primary`, or `navigation`)

    Fix: Validate `docs.json` with a JSON linter and check that all referenced pages exist.
  </Tab>

  <Tab title="Missing files">
    If your `docs.json` references a file that doesn't exist (for example, after renaming or deleting a page), the build fails.

    Fix: Update `docs.json` to match the actual file paths in your repository.
  </Tab>
</Tabs>

## Test locally before pushing

Use the Mintlify CLI to catch errors before they reach your repository:

```bash theme={null}
npm i -g mintlify
mintlify dev
```

The local dev server shows the same errors the build system would catch. Fix issues locally and push only when the local preview looks correct.

## Revert if needed

If a deploy broke your live site, the quickest recovery is to revert the commit in Git. Mintlify deploys the reverted version automatically on the next push.