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

MDX syntax errors

MDX is stricter than Markdown. Common mistakes:

• Unclosed JSX tags (for example, <Note> without </Note>)
• HTML entities that need escaping (use & instead of &, < 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.

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.

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.

Test locally before pushing

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

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.