How do I troubleshoot preview not working in a headless CMS?

When preview doesn’t work in a headless CMS, the issue is usually one of a few things: the CMS isn’t sending the right data, the frontend preview route isn’t wired correctly, authentication/cookies are missing, or the preview query isn’t being triggered.

Here’s a practical troubleshooting checklist:

1) Confirm the CMS preview setup

• Make sure preview/draft mode is enabled in the CMS.
• Verify the preview URL is correct and points to your frontend.
• Check whether the CMS expects a specific query parameter, token, or slug.

2) Verify the preview URL

Your CMS usually calls something like:

• https://your-site.com/api/preview?secret=...&slug=... or
• https://your-site.com/preview?document=...

Check:

• The route exists
• The secret/token matches
• The slug/path is correct
• The URL is publicly reachable

3) Check frontend preview route logic

In your frontend, confirm the preview route:

• Validates the secret/token
• Sets preview mode/cookies correctly
• Redirects to the intended page
• Handles missing/invalid parameters gracefully

Common bugs:

• Wrong query param name (slug vs path)
• Redirecting to the wrong route
• Not enabling draft/preview mode in the framework

4) Confirm the API query is using draft content

Your frontend data-fetching code may still be using published content.

Check that preview mode changes the CMS query to:

• include drafts/unpublished entries
• bypass cached published responses
• use the correct API token

Examples of issues:

• Preview flag not passed to the fetch function
• Cache is serving old published content
• Using a public endpoint that only returns published data

5) Inspect cookies and auth

Preview often depends on cookies or session state.

Check:

• Browser cookies are being set
• Cookies are allowed on the domain
• SameSite/Secure settings are correct
• The preview session isn’t blocked by cross-site restrictions

If preview opens in a different domain/subdomain, cookies may not persist.

6) Look for CORS or network failures

Open browser dev tools and inspect:

• Network tab for failed requests
• Console errors
• 401/403 unauthorized responses
• 404s on preview routes
• CORS errors from the CMS API

7) Disable caching temporarily

Preview can fail if your app or CDN caches content aggressively.

Try:

• Disabling ISR/cache for preview requests
• Adding Cache-Control: no-store for preview mode
• Bypassing CDN edge cache
• Checking framework-level caching defaults

8) Test the preview endpoint directly

Open the preview URL in the browser manually and verify:

• It returns the expected redirect or response
• The secret is accepted
• The URL slug is correct
• Draft content appears after redirect

9) Check CMS permissions

Some CMSs require:

• A preview API token
• Draft permissions for the user/editor
• Specific environment variables in production

Make sure the token used by the preview endpoint has access to drafts.

10) Debug with logs

Add logging in:

• The preview API route
• The content-fetching function
• The CMS webhook/preview trigger

Log:

• Incoming query params
• Whether preview mode is enabled
• Which API endpoint is used
• The final content ID/slug being fetched

11) Framework-specific gotchas

If you’re using a specific frontend framework, common issues include:

Next.js

• draftMode() / previewMode not enabled properly
• App Router vs Pages Router differences
• Fetch caching not disabled in preview
• Middleware interfering with preview cookies

Nuxt

• Draft mode not wired into server routes
• Incorrect runtime config or environment variables

Gatsby

• Preview plugin not configured
• Build-time data still being used instead of runtime preview data

Remix / Astro / SvelteKit

• Session cookie not persisting
• Route loader still fetching published data
• Missing server-side preview handling

12) Reproduce with the simplest possible test

Create a minimal preview test:

• Hardcode one known draft entry
• Bypass extra filters or transformations
• Fetch directly from the CMS with preview enabled
• Render the raw title/body

If that works, the issue is likely in your app logic rather than the CMS.

---

Quick diagnosis pattern

If preview:

• Opens but shows published content → data fetching/caching issue
• Redirects to the wrong page → slug/query param issue
• Does nothing / errors → preview route or secret mismatch
• Works locally but not in production → cookies, domain, CORS, or CDN cache issue

If you want, I can help you troubleshoot this for a specific stack like Next.js + Sanity, Contentful, Strapi, Prismic, or Storyblok.