Troubleshoot preview mode

If you are getting a preview error, try the steps below. The first section is for content editors and business users—things you can try without technical setup. The second section is a technical guide for developers when the issue needs code or configuration changes.

preview-error
Preview error in Canvas

For content editors and business users#

Try these steps first. No developer or technical setup required.

Sometimes the application doesn't respond within the default 10 second timeout and an error is shown. Click Reload and try again.

reload-preview
Reload preview

Check if the front-end application can load the preview URL correctly in another tab. From the menu in the preview panel, choose Open in new tab.

open-new-tab
Open new tab

If preview works in the separate tab:
The preview URL is fine; the iframe may be blocked by browser settings, Incognito mode, or security policies.

If preview doesn't work in a separate tab:
Share this page with your developer or use the technical guide below.

Browsers in Incognito or Privacy mode, or privacy-focused browsers (for example, Brave), can block visual editing in Canvas because of strict iframe security.

Turn off Incognito or Privacy mode, or use a different browser.

Chromium-based browsers (Google Chrome 142+, Microsoft Edge, Arc) may ask for permission to reach localhost or apps on your local network.

When loading a local development server in the preview iframe, the browser may prompt: "Look for and connect to any device on your local network." Click Allow for uniform.app. If you previously chose Block, click the lock icon in the address bar and set Local network devices to Allow. Learn more.

browser-local-network-access
Browser local network access

Ensure nothing is blocking the preview from loading in an iframe.

  • Try a different Chrome profile or a browser with no extensions.
  • Corporate IT or security extensions (e.g. strict content blocking) can prevent iframes from loading.

If none of the steps above fixed the issue, share this page with your developer or continue with the technical guide below.

If the user-facing steps didn’t resolve the preview error, work through the following checks. Use the Network panel in DevTools and filter by the preview URL to see failed or slow requests. You can also open the preview in a new tab from the preview panel to test the URL directly.

Open the browser console and DevTools when the preview fails. Errors there often explain why the iframed site didn’t load (e.g. CSP, CORS, or network errors).

Confirm the project has correct preview URLs configured:

  1. Open the preview URL dropdown in the preview panel.
  2. Select Manage preview settings.
  3. In Preview URLs, check that the selected URL is correct and returns a valid response when you open it in the same browser.
manage-preview-settings
Preview settings

Use iframetester.com to confirm your app can be embedded in an iframe.

If you see:

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

update your CSP to allow Uniform in frame-ancestors and script-src:

frame-ancestors 'self' https://uniform.app; script-src 'self' https://uniform.app;
  • HTTP status: The route may return 404 or 500. Ensure the route renders and returns 200.
  • Routing: The app may not have a route for the requested path. See Next.js or Nuxt 3 routing docs.
  • Package versions: Use Uniform packages v18.0.0+ in package.json for visual editing support.
  • Environment variables: Confirm required variables are set and correct (e.g. UNIFORM_PREVIEW_SECRET, API key, project ID). Check for typos in names and values.

Troubleshooting differs slightly for local development vs a deployed app.

For shared preview across the team, set the Preview URL to a remote deployment (e.g. Vercel or Netlify). If preview fails for a deployed app, focus on deployment and pipeline: check your host’s build and deployment logs.

Common issues for deployed applications:

  • Preview URL uses http instead of https
  • Preview URL points to localhost or another local URL
  • Server doesn’t support HTTPS
  • Preview URL doesn’t match the actual deployment URL
  • Latest code isn’t deployed
  • API key lacks required permissions

During development, the Preview URL often points to a local server:

http://localhost:3000/api/preview/?secret=<preview-secret>

Common issues for local applications:

  • Preview URL uses https instead of http
  • Front-end app / dev server isn’t running
  • App returns a rendering error which needs to be fixed before preview can be functional
  • App is running on a different port than the one in the Preview URL (e.g. multiple Next.js apps at once)
Last modified
Next
Rendering