Troubleshooting

Common issues and solutions for Mintlify documentation

This guide covers common issues you might encounter when working with Mintlify and how to resolve them.

Build errors

Syntax errors in MDX files

Problem: Build fails with parsing errors.

Solution: Check your MDX files for:

• Unclosed JSX tags
• Missing closing braces in component props
• Invalid frontmatter YAML syntax
• Special characters that need escaping

Run mintlify dev locally to identify the specific file and line causing the error.

Missing or invalid frontmatter

Problem: Pages don’t display correctly or build fails.

Solution: Ensure every MDX file has valid frontmatter:

---
title: Your page title
description: A brief description
---

Both title and description are required fields.

Navigation configuration errors

Problem: Build fails with navigation-related errors.

Solution: Verify your docs.json navigation structure:

• All page paths reference existing MDX files
• No duplicate page entries
• Proper JSON syntax (commas, brackets, quotes)
• Valid icon names from the Lucide library

Preview issues

Local preview not updating

Problem: Changes don’t appear in mintlify dev.

Solution:

1. Stop the dev server (Ctrl+C)
2. Clear your browser cache
3. Restart with mintlify dev
4. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)

Images not loading

Problem: Images show broken or don’t display.

Solution:

• Verify image paths are relative to the MDX file
• Check that images exist in your repository
• Ensure image files are committed to Git
• Use supported formats (PNG, JPG, SVG, GIF, WebP)
• Check file names don’t contain spaces or special characters

Components not rendering

Problem: Mintlify components display as plain text or don’t work.

Solution:

• Verify component syntax matches documentation
• Check for typos in component names (case-sensitive)
• Ensure props are properly formatted
• Close all component tags properly

Deployment issues

Build succeeds locally but fails in production

Problem: mintlify dev works but deployment fails.

Solution:

• Check for environment-specific file paths
• Verify all files are committed and pushed to Git
• Review deployment logs for specific error messages
• Ensure docs.json is valid JSON (use a JSON validator)

Changes not appearing after deployment

Problem: Deployed site doesn’t reflect recent changes.

Solution:

1. Verify changes are pushed to the correct branch
2. Check deployment status in your Mintlify dashboard
3. Clear CDN cache if using custom domain
4. Wait 2-3 minutes for propagation
5. Hard refresh your browser

Custom domain not working

Problem: Custom domain shows errors or doesn’t connect.

Solution:

• Verify DNS records are correctly configured
• Allow 24-48 hours for DNS propagation
• Check that CNAME points to your Mintlify subdomain
• Ensure SSL certificate has been issued (can take up to 24 hours)

Search issues

Search not finding pages

Problem: Search doesn’t return expected results.

Solution:

• Ensure pages are included in navigation (hidden pages aren’t indexed)
• Add descriptive title and description in frontmatter
• Include relevant keywords in page content
• Wait for search index to rebuild after deployment (5-10 minutes)

Search showing outdated content

Problem: Search results show old content.

Solution:

• Redeploy your documentation to trigger reindexing
• Clear browser cache
• Wait 10-15 minutes for search index to update

API documentation issues

OpenAPI spec not loading

Problem: API reference pages don’t generate or show errors.

Solution:

• Validate your OpenAPI spec using Swagger Editor
• Ensure the spec file path in docs.json is correct
• Check that the spec is valid JSON or YAML
• Verify the spec version is supported (OpenAPI 3.0+)

API playground not working

Problem: Try it out feature doesn’t work.

Solution:

• Check CORS configuration on your API server
• Verify authentication setup in docs.json
• Ensure API endpoints are accessible
• Check browser console for error messages

Authentication issues

Users can’t access protected docs

Problem: Authentication fails or loops.

Solution:

• Verify JWT configuration in docs.json
• Check token expiration settings
• Ensure authentication endpoint is accessible
• Review authentication logs in dashboard
• Test with a fresh browser session (incognito mode)

Performance issues

Slow page loads

Problem: Documentation loads slowly.

Solution:

• Optimize image sizes (use WebP format, compress images)
• Reduce number of custom scripts
• Minimize use of large embedded content
• Consider lazy loading for heavy components

Build takes too long

Problem: Deployment builds are slow.

Solution:

• Reduce number of pages if possible
• Optimize image assets
• Remove unused files from repository
• Check for circular dependencies in snippets

Git integration issues

GitHub/GitLab connection fails

Problem: Can’t connect repository or deployments don’t trigger.

Solution:

• Verify repository permissions (Mintlify needs read access)
• Check that webhook is properly configured
• Ensure branch name matches configuration
• Re-authenticate Git integration in dashboard

Merge conflicts in docs.json

Problem: Navigation changes cause merge conflicts.

Solution:

• Pull latest changes before editing navigation
• Use web editor for navigation changes when possible
• Coordinate with team on navigation updates
• Keep navigation changes in separate commits

Getting help

If you’re still experiencing issues:

1. Check the status page for known incidents
2. Search GitHub discussions for similar issues
3. Review deployment logs in your dashboard
4. Contact support with:
   • Detailed description of the issue
   • Steps to reproduce
   • Error messages or screenshots
   • Your repository URL (if public)