How to debug a publish or optimization warning

This guide covers two site publishing errors—publishing and optimization errors—and their resolution strategies.

Publishing errors

If a publishing error occurs, you’ll see a toast notification:

“Failed to publish because there is an error on a page.”

A Review button will also be provided.

Common causes of publishing errors

Dynamic runtime errors:

  • The site compiler timed out while waiting for a component to build.

  • Example error in the web inspector: ensureComponentsInLoader: Component loader not updated in time.

  • Solution: Retry publishing. If the issue persists, fix or remove the problematic component.

Missing used components:

  • A component might no longer be available due to a file rename, function rename, or a loading error.

  • Clicking the Review button will highlight the missing component as a grey error placeholder in the layer panel.

Solution: Fix or replace the missing component.

Shows a component error in the Framer editor.

Optimization errors

Framer sites are built using React. Optimization "pre-renders" your site on the server, ensuring visitors see content immediately instead of a blank page while React loads in the background. Optimization is crucial for:

  • SEO: Ensures search engines see content instead of an empty page.

  • User experience: Reduces load times for visitors.

You can check optimization status under Settings → Domains or Settings → Versions.

The Versions section in the Settings.

Common cause: custom code components or overrides

Custom code that relies on browser-specific APIs, such as window, document, or navigator, may not optimize effectively. Framer’s server pre-renders pages without a browser environment, rendering these APIs unavailable.

To resolve these optimization errors, avoid using browser-dependent JavaScript during server-side rendering. Instead, consider using alternatives like CSS media queries in place of window.innerWidth.

Customizing based on user data

If your component needs browser-specific information like document.cookie or navigator.language:

Use placeholders: Create a component that shows a placeholder while loading, then updates after the page loads. Example: framer-optim-1.jsx.

Opt-out of optimization: Components can bypass optimization, but their content won’t be accessible to search engines. Use this method sparingly. Example: framer-optim-2.jsx.

For overrides: Use the same approach as components to handle overrides. Example: framer-optim-3.jsx.

Still experiencing the issue after following the steps above? Create a support ticket in the Community.