> ## Documentation Index
> Fetch the complete documentation index at: https://your-third-ep5.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Common Mintlify Issues

> Diagnose and fix frequent Mintlify problems including broken links, missing images, search failures, slow publishes, and custom domain 404s.

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.

<Accordion title="Broken links in published documentation">
  **Symptom:** Clicking a link returns a 404 or jumps to the wrong page.

  **Cause:** The link path does not match the actual file route, or the target page was moved or renamed without updating references.

  **Fix:**

  1. Check the link path in your Markdown or MDX file. Use absolute paths starting from the content root, for example `/guides/authentication`.
  2. Verify the target file exists at that exact path, including case sensitivity.
  3. If you renamed a file, update all internal links that point to the old path.
  4. Rebuild and redeploy to confirm the links resolve.
</Accordion>

<Accordion title="Images not loading">
  **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.
</Accordion>

<Accordion title="Search not returning results">
  **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.
</Accordion>

<Accordion title="Slow publish times">
  **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.
</Accordion>

<Accordion title="404 on a custom domain">
  **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.
</Accordion>

If these steps do not resolve your issue, contact the support team at [**support@mintlify.com**](mailto:support@mintlify.com) with a description of the symptom, the page or project affected, and any error messages you see.