> ## Documentation Index
> Fetch the complete documentation index at: https://help-center-starter-replace-template-content.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Performance issues

> Diagnose slow builds, slow page loads, and other performance problems in Mintlify.

Performance problems in Mintlify fall into two categories: slow build times and slow page loads. The fixes are different for each.

## Slow builds

If your deployments are taking longer than expected, common causes include:

**Large images** — Unoptimized images dramatically slow builds. Compress images before adding them to your repository, or host them externally (Cloudinary, S3) and reference them by URL.

**Many pages** — Sites with thousands of pages take longer to build. This is usually not a problem until you reach 2,000+ pages.

**External data fetching** — If your docs fetch data from external APIs at build time, slow API responses extend build times. Cache responses or use static data where possible.

### Check your build time trend

Go to **\[Project] → Deployments** and look at the build duration column. If build times have increased gradually, it's likely due to content growth. A sudden jump suggests a recently added page or image is the culprit.

## Slow page loads

If your docs pages load slowly for readers, common causes include:

**Large images on the page** — Audit your pages for large embedded images. Use smaller images or reference external images so they load from a CDN rather than your repository.

**Custom JavaScript** — Scripts added via Google Tag Manager or custom `<script>` tags can significantly slow page loads if they're not performance-optimized.

**CDN propagation** — After a new deployment, CDN caches need time to propagate globally. Pages may load slightly slower for 5–10 minutes after a deploy.

## Checking your build performance

Use the [Mintlify CLI](https://mintlify.com/docs) to validate your docs locally:

```bash theme={null}
mintlify dev
```

The local dev server shows warnings for pages with issues (large images, invalid components) that could affect build or load performance.

## Reporting a performance issue

If you've ruled out the common causes and pages are still loading slowly, [contact support](/support/contact-support) and include:

* Your project URL.
* A specific page URL that loads slowly.
* A screenshot of the network panel in browser dev tools showing load times.