Cumulative Layout Shift (CLS) too high

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

<!-- Always set width/height (or aspect-ratio) on media -->
<img src="hero.jpg" width="1200" height="630" alt="">
/* Reserve space for dynamic embeds */
.ad-slot { min-height: 250px; }
/* Avoid inserting content above existing content after load */

How to diagnose Frontend errors

Modern frontend errors are dominated by the boundary between server rendering and client hydration. A hydration mismatch means the HTML the server produced does not match what the client would have rendered, usually because of a date, a random value, a browser-only API, or user-specific content rendered during SSR. The second large family is bundler resolution, where the error names a module but the real cause is configuration.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. For hydration errors, read the diff the framework prints: React, Nuxt and Astro all show the mismatched node. Look for Date, Math.random, window, localStorage and locale formatting in that subtree.
2. Deliberately defer browser-only rendering with a mount effect or the framework's client-only directive rather than suppressing the warning.
3. For resolution errors, run the bundler with verbose logging and check whether the package ships ESM, CJS or both, and whether your conditions / mainFields configuration selects the right one.
4. Diagnose layout shift with Lighthouse or the Performance panel's Layout Shift regions. Nearly all CLS comes from images without dimensions, injected banners, and web fonts without font-display: swap.
5. Reproduce production build failures locally with NODE_ENV=production; dev servers are far more forgiving than production builds.

Tools worth reaching for

• Lighthouse
• Chrome Performance panel
• vite build --debug
• webpack-bundle-analyzer
• React DevTools

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 web.dev

Related Frontend errors

• Angular: NG0100: ExpressionChangedAfterItHasBeenCheckedErrorA binding produced one value during change detection and a different one when Angular…
• Astro: client hydration mismatchAn interactive island rendered different markup on the client than the server, or a client…
• Blocked aria-hidden on an element because its descendant retained focusChrome refuses to hide a subtree from assistive technology while the focused element is…
• CORS: web font blocked by Access-Control-Allow-OriginFonts are fetched with CORS. A cross-origin font without the right ACAO header is blocked…
• CSS: @import rules must precede all other rulesThe CSS specification only allows @import at the top of a stylesheet, after @charset and…
• DOMException: play() failed because the user didn't interact with the documentBrowsers block audible autoplay until the page has received a user gesture. play() returns a…
• esbuild: Could not resolve "X"esbuild could not find a module: it is not installed, the path/extension is wrong, or it is a…
• Failed to load module script: expected a JavaScript module but got text/htmlThe browser requested a .js module and the server returned an HTML page. That is almost…

See all 23 Frontend errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.