Skip to main content

Troubleshoot preview mode

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

preview-error
Preview error in Canvas

Check preview URL settings​

First check if your project has the correct preview URL configured:

  1. In Uniform, open your project
  2. Navigate to Settings > Canvas Settings
  3. Check the value for Preview URL

Check front end application​

Next check if the front end application is able to resolve the preview URL correctly.

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.

Debugging tips

In Canvas 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.

Common issues for front-end applications​

  • 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 does not 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 contextual editing is supported.
  • Browsers in Incognito or Privacy mode or privacy-focused browsers (e.g. Brave) may have issues with contextual editing in Canvas. Turn off Incognito or Privacy mode or use a differnt browser.
  • Wrong or missing environment variables:
    • Check if all required environment variables are set (e.g. UNIFORM_PREVIEW_SECRET).
    • Check if the environment have the correct values (e.g. Uniform API key, project ID, ...).
    • Check for typos in environment variables names or values.

Troubleshooting local vs remote applications​

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

Deployed 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 (e.g. Vercel or Netlify).

If preview mode does not 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.

Common issues for deployed applications​

  • Preview URL starts with http instead of https
  • Preview URL points to a local development URL (e.g. localhost)
  • The server does not support https connections
  • Preview URL is different to the URL of the deployment
  • The latest version of the application code is not deployed
  • API key does not have the right permissions

Local front-end application​

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

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

Common issues for local front-end applications​

  • Preview URL starts with https instead of http
  • Front end application is not 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.

Incognito Mode​

Browsers like Google Chrome would block cookies and localStorage usage within iFrames during Incognito Mode. As Uniform Contextual Editing relies on them to properly manage A/B Tests and Personalization components Preview will not work. Unless you disable 3rd party cookies blocking in browser settings, which is not 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 updated on