Skip to main content
Contentstack MCP profile hub is in general availability!

Live Preview not working? A symptom index

•
13 min read

Live Preview problems rarely announce their cause. The panel stays blank, or it shows published content, or the edit button does nothing, and the error in the console (if there is one) points at a postMessage library you never installed. Most of the time the setup is 90% right and one contract between the CMS, your site and the Preview API is broken.

This guide is an index. Find your symptom in the table, read the short section for the cause and the fix, and follow the link into The Ultimate Guide to Contentstack Visual Building when you want the full explanation. It applies to CSR, SSR and SSG sites on any host.

What you'll learn

  • How to map a Live Preview or Visual Editor symptom to the contract it breaks

  • The fixes for blank iframes, dropped hashes, cached previews and dead edit tags

  • What error_code 382, "SDK not initialized" and the en-us locale default mean

  • How to keep preview code and edit buttons out of production

Symptoms

What you see

Likely cause

Section under Fix it

Blank panel, "<host> refused to connect", SSO or password prompt in the panel

The site can't be framed

The iframe can't load your site

blocked by CORS policy ... 'unknown' address space on localhost

Browser private network rules

The iframe can't load your site

Preview opens the home page, or the slug lands inside a query parameter

Base URL contains a query string

The preview URL is wrong

Preview opens a 404 with locale=en-us in the URL

Locale in the URL or in edit tags defaults to en-us

The preview URL is wrong

"Live Preview SDK not initialized" in the setup status

init() never runs in the browser, or runs too late

The SDK doesn't initialize

"Preview Service not enabled" or "Outdated SDK"

Old SDK or mismatched region hosts

The SDK doesn't initialize

Preview shows published content, not the draft

Hash missing, or the fetch goes to the delivery host

Drafts never show up

First page shows the draft, the next page shows published content

Navigation or middleware drops the hash

Drafts never show up

Edits save, "entry updated successfully", page never changes

A cache serves the old HTML or data

Updates arrive but the page doesn't change

One editor sees another editor's draft

Shared SDK instance in SSR

Updates arrive but the page doesn't change

Static pages never show drafts

SSG without a preview mode

Updates arrive but the page doesn't change

Edit tags present, clicking does nothing

Wrong locale or path in data-cslp

Edit tags don't resolve

Edit tags work with REST, not with GraphQL

edges/node layers in the tag path

Edit tags don't resolve

error_code 141 with include_all in preview only

Preview resolves drafts too and hits reference limits

Preview data differs from delivery

Empty nested references or null JSON RTE in preview

Same query, different resolution on preview

Preview data differs from delivery

error_code 382, "The Live Preview tracker is invalid or no longer exists" on public traffic

A hash leaks into normal requests

Tracker errors on the live site

Preview stops working after the tab sits idle for a while

The session hash expired

Tracker errors on the live site

Edit button element in the production DOM

SDK imported on production pages

Preview code leaks into production

Works on localhost, does nothing when deployed

Environment difference, not a product limit

Works locally, not deployed

Why it happens

Contentstack concept: Live Preview is a chain of contracts. The CMS frames your site in an iframe. The Live Preview SDK in the browser does a postMessage handshake with the CMS. The CMS hands your site a short-lived live_preview hash. Your fetch sends that hash and a preview token to the Preview API host. Nothing in between caches the response, and your UI re-renders with the new data.

Every symptom above is one broken link in that chain. The debugging chapter walks the chain in six steps. If you want the mental model first, read How Live Preview works.

Before you fix anything, turn on Settings > Live Preview > Display Setup Status. It reports "could not connect to website", "SDK not initialized", "outdated SDK", "Preview Service not enabled" and a missing default environment in real time.

Fix it

The iframe can't load your site

Open the preview URL in a normal browser tab. If it loads there and fails in the panel, the difference is framing or auth.

  • X-Frame-Options or CSP. A site that sends X-Frame-Options: DENY or SAMEORIGIN, or a Content-Security-Policy whose frame-ancestors leaves out the Contentstack app, can't be framed. Allow the app origin on preview and staging hosts only:

Content-Security-Policy: frame-ancestors 'self' https://*.contentstack.com
  • SSO, OAuth or deployment protection. Identity providers often refuse to render in an iframe, and cookie-based gates have to survive a cross-site context. Use Always Open in New Tab in the Visual Experience settings (needs SDK v4.0.0 or later) so the site opens in its own tab, or keep the preview host out of the SSO-gated set. For basic auth, check that the browser isn't blocking third-party cookies before you assume a bug.

  • CORS "address space" on localhost. Permission was denied for this request to access the 'unknown' address space is the browser blocking a public page (the Contentstack app) from reaching a private address. No server-side CORS header changes that. Expose your dev server through a tunnel, or preview against a deployed environment.

The preview URL is wrong

Live Preview builds the iframe URL from the environment's base URL plus the entry's URL field. It joins them as a string. If the base URL already contains a query string, for example a protection-bypass token, the entry path gets appended to the last parameter's value: https://site.example/?token=abc%2Fmy-page. Keep query strings out of the base URL.

If the URL carries locale=en-us and your stack has no en-us, check that the environment has a base URL for every locale you preview, and that the locale picked in the preview panel is one your stack has. Then check your edit tags (see "Edit tags don't resolve" below), because they default to en-us on their own.

If the iframe opens the wrong page for a referenced entry or a multi-site setup, the URL field on the entry doesn't describe where it renders. Fix the URL field, or use custom preview URL patterns if your plan includes them.

The SDK doesn't initialize

"SDK not initialized" means the CMS never received the SDK's init message. The usual causes:

  • init() only runs on the server, or in a component that never mounts in the browser.

  • init() runs after your first fetch.

  • The SDK is older than v4. Update @contentstack/live-preview-utils.

Initialize once, in the browser, in its own module so a re-render can't reset the config:

// lib/live-preview.ts
import ContentstackLivePreview, { type IStackSdk } from "@contentstack/live-preview-utils";
import { stack } from "./contentstack"; // the same instance your pages query with

export function initLivePreview() {
  ContentstackLivePreview.init({
    enable: true,
    ssr: false, // true for SSR sites that reload the iframe on change
    stackSdk: stack.config as IStackSdk, // CSR with the Delivery SDK
    stackDetails: {
      apiKey: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY!,
      environment: process.env.NEXT_PUBLIC_CONTENTSTACK_ENVIRONMENT!,
      branch: process.env.NEXT_PUBLIC_CONTENTSTACK_BRANCH ?? "main",
    },
    clientUrlParams: { host: "app.contentstack.com" }, // your region's app host
    editButton: { enable: true },
  });
}

"Preview Service not enabled" after you migrated usually means a host mismatch. Compare the delivery host, the preview host and clientUrlParams.host: they all have to belong to the stack's region. Pass branch in stackDetails when you preview anything other than main. The CSR chapter has the full init reference.

Drafts never show up

The page loads, the SDK is connected, and you still see published content. The hash isn't reaching the fetch, or the fetch goes to the wrong host.

  1. Check the iframe src for live_preview=. If it's missing, check the environment's base URL in the Live Preview settings.

  2. Check the network tab. Preview requests go to the region's preview host (for example rest-preview.contentstack.com) with preview_token and live_preview headers. A request to cdn.contentstack.io returns published content, by design.

  3. Under SSR, read the hash from the request on every request and pass it to a stack instance created for that request:

const stack = createStack(); // per request, never a module-level singleton
const hash = searchParams.live_preview;
if (hash) {
  stack.livePreviewQuery({
    live_preview: hash,
    contentTypeUid: searchParams.content_type_uid,
    entryUid: searchParams.entry_uid,
  });
}

With the Delivery SDK, there has to be one stack instance per request, and it has to be the one you query with. The hash only lands on the instance that receives it. If you fetch without the SDK, your code owns both jobs: read the hash and switch the request to the preview host.

If the first page works and the next one doesn't, navigation lost the hash. Middleware, redirects and <Link> components drop query parameters unless you carry them. The SSR chapter shows how to propagate the hash, and Middleware and database-backed architectures covers proxies and BFFs.

Updates arrive but the page doesn't change

The CMS reports "Live Preview entry updated successfully", the SDK reloads the iframe or fires onEntryChange, and the page shows the same thing. Something cached it.

  • CDN or route cache. Under SSR the SDK reloads the iframe. If a CDN or a static route returns the same HTML, nothing changes. Send Cache-Control: no-store on any request that carries live_preview, and bypass framework caches for it.

  • Shared SDK instance. One editor seeing another's draft is a module-level stack mutated per request. Create the stack per request, as above.

  • SSG. A static page is built once, so preview parameters never reach it. Use your framework's preview or draft mode and render dynamically when live_preview is present. The SSG chapter covers Next.js, Nuxt, Gatsby and Astro.

  • CSR state. Check that onEntryChange is registered and that the callback refetches and sets state, not a stale closure.

Edit tags don't resolve

Edit tags are data-cslp attributes in the form content_type.entry_uid.locale.field_path. When the locale or the path is wrong, nothing throws. The tag just never maps to a field.

  • Locale. addEditableTags(entry, contentTypeUid, tagsAsObject, locale) defaults locale to en-us. Pass the locale of the entry you render, every time.

  • entry.$ is undefined. The call didn't run on that entry, or tagsAsObject isn't true for JSX.

  • References. Tag referenced entries separately, with their own content type. References come back as arrays, so the path is page.author[0].$?.name.

  • GraphQL. addEditableTags expects the REST shape. A GraphQL response produces paths like imageConnection.edges.0.node.url, which don't exist on the entry. Request system { uid content_type_uid } and reshape the response before tagging, as shown in Edit tags and Visual Editor.

  • Fullscreen or new tab. The button works, but the overlay or a separate browser tab hides the highlighted field. Keep the entry editor visible.

Preview data differs from delivery

Run the identical query against delivery and preview for the same entry and compare. If only preview fails:

  • error_code 141 with include_all. The Preview API resolves unpublished and draft references as well as published ones, so a deep include_all_depth hits the reference resolution limit sooner than it does on delivery. Lower the depth, or include the specific reference paths you render. Nested references empty, or error 141 covers the limits.

  • Empty nested connections or null JSON RTE on GraphQL preview. Try the same query on REST preview. If REST returns the data, the difference is in the GraphQL preview resolution, and REST preview is a practical way to keep editors unblocked. GraphQL errors decoded covers the depth and cost limits.

Tracker errors on the live site

error_code 382
The Live Preview tracker is invalid or no longer exists. Create a new tracker to continue.
The requested tracker was created for the 'dev' branch. Access using the 'main' branch is not allowed.

When these show up on ordinary site traffic, a preview hash is being sent where it doesn't belong. The hash is a short-lived session credential tied to one stack and branch. Once it expires, or reaches a request for another stack or branch, the Preview API rejects it with an HTTP 400 that your app may surface as a 500.

Send live_preview and the preview host only on requests that belong to a preview session. Never store a hash in a module-level client, a cached fetch config or a cookie that outlives the session. If one frontend serves several stacks, make sure each request resolves the stack the hash was created for.

The same expiry explains a preview that stops responding after the tab sits idle. Close and reopen Live Preview to start a new session.

Preview code leaks into production

Importing @contentstack/live-preview-utils is enough to add the edit button element (#cslp-tooltip) to the page, even if you never call init(). To keep it out of production:

  • Build production with PURGE_PREVIEW_SDK=true (or REACT_APP_PURGE_PREVIEW_SDK=true). Use SDK 4.4.0 or later.

  • Or import the SDK dynamically, only when the page is being previewed.

  • Set editButton.exclude: ["outsideLivePreviewPortal"] so the button never renders outside the preview panel, and editButton.includeByQueryParameter: false so ?cslp-buttons=true can't turn it back on.

  • Set cleanCslpOnProduction: true to strip data-cslp attributes outside preview.

Works locally, not deployed

Live Preview works on deployed environments, so treat this as a difference hunt. Check in this order: framing headers and auth on the deployed host, HTTPS, a CDN or static cache in front of the preview route, the preview token and region host in that environment's variables, and whether the preview route is prerendered so searchParams never arrive. A working localhost .env proves nothing about the deployed one.

Check that it worked

  • Setup status is green. Every check under Display Setup Status passes.

  • The hash is in the iframe. ContentstackLivePreview.hash returns a value inside the panel. Outside the panel it's empty, which is expected.

  • Events fire. Register ContentstackLivePreview.onEntryChange(() => console.log("change")), edit a field, and see one log per change.

  • The right host answers. The network tab shows requests to the preview host with live_preview and preview_token headers, and Cache-Control: no-store on the response.

  • Navigation keeps the session. Click two links inside the preview and confirm the draft still shows.

  • Edit tags resolve. Inspect a data-cslp attribute: the locale matches the entry and the path has no edges or node in it.

Prevent it

  • Decide preview versus delivery in one place, keyed on the presence of the hash.

  • Create the stack per request on the server. Never put preview state in a module-level variable.

  • Bypass every cache when live_preview is present, and test it on the deployed host, not just localhost.

  • Pass the locale to addEditableTags and tag referenced entries with their own content type.

  • Strip the SDK from production builds and exclude the edit button outside the portal.

  • Run the preview checklist from the debugging chapter on every new page type.

Key takeaways

  • Every symptom is one broken link: framing, init, hash, preview host, cache, re-render or edit tag path.

  • Published content in preview means the hash didn't reach the fetch, or the fetch went to cdn.contentstack.io.

  • error_code 382 on public traffic means a preview hash leaked out of the preview session.

  • addEditableTags defaults the locale to en-us. Pass it explicitly.

  • Turn on Display Setup Status first. It catches most configuration errors before you open devtools.

Next steps

Frequently asked questions

  • Why does Live Preview show published content instead of my draft?

    The live_preview hash is not reaching the request that fetches content, or that request goes to the delivery host instead of the preview host. Check the iframe URL and the network tab for both.

  • What does error_code 382 "tracker is invalid" mean?

    A request carried a preview hash that expired or belongs to another stack or branch. It usually shows up when a hash leaks into normal site traffic, so only send live_preview on requests that are part of a preview session.

  • Why does the edit button show on my production site?

    Importing the SDK on production pages is enough to create the button element. Exclude it with editButton.exclude set to outsideLivePreviewPortal, or strip the SDK at build time with PURGE_PREVIEW_SDK=true on SDK 4.4.0 or later.

  • Why do my edit tags point at en-us when my stack has no en-us locale?

    addEditableTags takes the locale as an optional fourth argument and defaults it to en-us. Always pass the locale of the entry you render.

  • Live Preview works on localhost but not on the deployed site. Where do I start?

    Check framing headers and auth on the deployed host first, then any CDN or route cache in front of the preview route, then the preview token and region host for that environment.