Troubleshoot preview mode

If you are getting a preview error, here are some troubleshooting tips to help you resolve common issues.

preview-error
Preview error in Canvas

First check if your project has correct preview URLs configured:

  1. In Uniform, open your project.
  2. Navigate to Settings > Preview.
  3. In the Preview URLs section check that for the currently selected preview URL that the URL is correct and is responding if you are making a separate request to it from the same browser.

Check if the front end application is able to resolve the preview URL correctly in another tab (from the menu in the preview panel). If it does open in the new tab, try reloading the preview.

Preview mode will show an error if a request to the preview URL responds with an HTTP error status code such as a 404 (page not found) or 500 (server error) or if there are any other errors that prevent the page from loading into the preview panel.

tip

Debugging tips: In Uniform you can inspect if the preview URL is correctly loaded using the Network panel of your browsers DevTools. You can filter the network requests for the preview URL and check if any errors are returned.

Also, you can try opening the current page in a new tab by clicking on the "Open in new tab" button on the preview panel.

This can yield additional insight why the iframed site cannot be loaded.

Using this tool, verify that your application can be iframed.

If you are getting this error:

Refused to frame 'https://yoursite.net/' because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'none'".

you will need to adjust the CSP policy's and include https://uniform.app for frame-ancestors and script-src directives:

frame-ancestors 'self' https://uniform.app; script-src 'self' https://uniform.app;

  1. If reloading doesn't help, check to see that you don't have any Chrome extensions that may block the origin from being iFramed (try running Uniform in a different Chrome profile that has no extensions installed)

  2. Make sure browser settings aren't preventing preview from loading iFrames from the origin.

  • The requested route is returning an HTTP error status code such as a 404 or 500. Ensure that the route can be rendered correctly and returns a HTTP 200 response.
  • The front-end application doesn't support rendering of the requested route.
  • Front-end application code uses outdated Uniform packages: update package.json to use the latest Uniform package versions (v18.0.0+) to ensure that visual editing is supported.
  • Browsers in Incognito or Privacy mode or privacy.focused browsers (for example, Brave) may have issues with visual editing in Canvas. Turn off Incognito or Privacy mode or use a different browser.
  • Wrong or missing environment variables:
    • Check if all required environment variables are set (for example, UNIFORM_PREVIEW_SECRET).
    • Check if the environment have the correct values (for example, Uniform API key, project ID, ...).
    • Check for typos in environment variables names or values.

The steps of troubleshooting a preview error may differ slightly depending on whether you are working with a remotely deployed or local front-end application.

To be able to have a common preview for multiple collaborators in you your team you will want to configure your Preview URL to point to a deployment on a remote server (for example, Vercel or Netlify).

If preview mode doesn't work for a deployed front-end application then it often is an issue with the deployment settings and pipeline. Check the build logs of your hosting provider to see if there are any build and deployment issues.

  • Preview URL starts with http instead of https
  • Preview URL points to a local development URL (such as localhost)
  • The server doesn't support https connections
  • Preview URL is different to the URL of the deployment
  • The latest version of the application code isn't deployed
  • API key doesn't have the right permissions

When you are in active development of your project it's common to point the preview URL to your front end application that's running locally on your computer (such as http://localhost:3000/api/preview/?secret=<preview-secret>).

note

Best practice: You can use separate Uniform projects to represent development environments like Dev, Staging and Production. Then you can configure different preview URLs for each development environment.

If you want to learn more about this approach then watch this video or read this blog post.

  • Preview URL starts with https instead of http
  • Front end application isn't running
  • Front end application is running under a different port than configured for the Preview URL. This often happens if you have multiple Next.js applications running at the same time.

Browsers like Google Chrome would block cookies and localStorage usage within iFrames during Incognito Mode. Uniform visual editing relies on them to properly manage A/B Tests and personalization components. As such, preview won't work unless you disable 3rd-party cookies blocking in browser settings, which isn't recommended. For more information see the Chromium documentation on this topic.

This case is valid for any other occasion you see following error in your console:

Uncaught DOMException: Failed to read the 'localStorage' property from 'Window': Access is denied for this document.
Last modified
Next
Rendering