Skip to main content
This page covers common issues you may encounter when setting up or maintaining your Mintlify documentation.

​
Build and deployment issues

  1. Check deployment status: Visit the Mintlify dashboard to verify your deployment completed successfully.
  2. Clear browser cache: Hard refresh your browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows) or try incognito mode.
  3. Verify file is in navigation: Pages must be listed in docs.json navigation to be accessible.
  4. Check for build errors: Run mintlify dev locally to catch syntax or configuration errors before deploying.
Common causes:
  • Invalid JSON in docs.json: Use a JSON validator to check for syntax errors like trailing commas or missing quotes.
  • Missing required frontmatter: Every MDX file needs at minimum a title field.
  • Broken internal links: Links to pages that don’t exist will cause build warnings. Use relative paths without file extensions.
Run mintlify dev locally to see detailed error messages.
  1. Ensure preview deployments are enabled in your dashboard settings.
  2. Check that your GitHub/GitLab integration has the correct permissions.
  3. Verify the PR is targeting the correct branch configured in your dashboard.

​
Content and formatting issues

  • Check component syntax: Components are case-sensitive. Use <Note> not <note>.
  • Close all tags: Self-closing tags need a slash: <br /> not <br>.
  • Escape special characters: Use \{ to display literal curly braces in text.
  • Check for JSX conflicts: Angle brackets in code examples may need to be wrapped in backticks.
Ensure you specify the language after the opening backticks:
```javascript
const example = "highlighted";
```
Supported languages include: javascript, typescript, python, bash, json, yaml, mdx, and many more.
  1. Check the path: Use paths relative to your docs root, starting with /.
  2. Verify file exists: Ensure the image file is committed to your repository.
  3. Check file format: Supported formats include PNG, JPG, GIF, SVG, and WebP.
  4. File size: Very large images may fail to load. Optimize images under 1MB.
![Alt text](/images/my-image.png)
Ensure proper Markdown table syntax:
  • Header row must be followed by a separator row with dashes
  • Each row must have the same number of columns
  • Pipes must align (though this is optional)
| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
  1. Add to navigation: Pages must be listed in docs.json under navigation.
  2. Check the path: The path in navigation should match the file path without the .mdx extension.
  3. Verify file location: The MDX file must exist at the specified path.
"pages": ["folder/my-page"]  // matches folder/my-page.mdx

​
Custom domain issues

  1. Verify DNS settings: Check that your CNAME record points to cname.mintlify.com.
  2. Wait for propagation: DNS changes can take up to 48 hours to propagate.
  3. Check SSL certificate: Mintlify automatically provisions SSL, but this can take a few minutes after DNS propagation.
  4. Verify in dashboard: Ensure the custom domain is correctly configured in your Mintlify dashboard.
SSL certificates are automatically provisioned. If you see certificate errors:
  1. Wait 10-15 minutes after DNS propagation for certificate provisioning.
  2. Clear your browser’s SSL cache or try a different browser.
  3. Verify your DNS is correctly pointing to Mintlify’s servers.

​
Local development issues

Install the Mintlify CLI globally:
npm install -g mintlify
Or use npx to run without installing:
npx mintlify dev
  1. Stop the dev server (Ctrl+C)
  2. Clear the .mintlify cache folder in your project
  3. Restart with mintlify dev
The default port is 3000. If it’s in use, specify a different port:
mintlify dev --port 3001

​
Getting more help

If you’re still experiencing issues:
  1. Check the status page for any ongoing incidents.
  2. Search the GitHub discussions for similar issues.
  3. Contact support through the Mintlify dashboard or at hi@mintlify.com.
For API-specific issues, see the API playground troubleshooting guide.