Skip to main content
Most Mintlify issues have a quick cause and a clear fix. Use the guides below to identify what you are seeing, understand why it happens, and resolve it without waiting for support.
Symptom: Image placeholders appear instead of your uploaded images.Cause: The image path is incorrect, the file is not committed to the repository, or the image format is unsupported.Fix:
  1. Confirm the image file is in your project directory, usually under an images or assets folder.
  2. Use a relative path from the Markdown file to the image, for example ../images/diagram.png.
  3. Supported formats are PNG, JPG, GIF, and SVG. WebP is not supported.
  4. Commit the image file and redeploy.
Symptom: The search bar shows no matches for content you know exists.Cause: The search index has not been rebuilt after recent changes, or the content is in a file excluded from indexing.Fix:
  1. Trigger a fresh deploy. The search index rebuilds automatically after each successful deployment.
  2. Wait two to three minutes after deployment for indexing to complete.
  3. Check that the page is not hidden behind noindex frontmatter or excluded from navigation.
  4. If the issue persists, clear your browser cache and try again.
Symptom: Deployments take much longer than usual or time out.Cause: Large image files, excessive page counts, or a large dependency tree can slow the build process.Fix:
  1. Compress images before adding them. Aim for under 200 KB per image.
  2. Remove unused pages or assets from the repository.
  3. Split very large docs into multiple projects if possible.
  4. Check the build logs for warnings about slow steps and address them.
Symptom: Your custom domain shows a 404 for all pages, but the default Mintlify URL works.Cause: DNS records are missing or incorrect, or the domain has not finished propagating.Fix:
  1. In Mintlify, go to Settings > Domain and copy the required DNS records.
  2. Add the CNAME or A records at your DNS provider exactly as shown.
  3. Verify propagation with a DNS lookup tool.
  4. Return to Mintlify and click Verify domain. If verification fails, double-check record values and TTL settings.
If these steps do not resolve your issue, contact the support team at support@mintlify.com with a description of the symptom, the page or project affected, and any error messages you see.