Why Headless WordPress Preview Stops Working and How to Fix It

When preview opens the homepage, the wrong post, or a 404, the failure is usually in URL mapping rather than draft retrieval. In many headless setups, the frontend never reaches the intended resource, so changing GraphQL queries, REST filters, or revision logic fixes nothing.

What usually goes wrong

• A preview link is built from a slug that has changed, is duplicated, or is not yet published.
• The app tries to preview content on its public route instead of a dedicated preview entry route.
• The CMS generates frontend URLs for the wrong environment: production domain, local host, branch deploy, or mismatched protocol.

A safer pattern is to route preview by a stable identifier such as post ID, database ID, or UUID, then resolve the draft server-side. Slugs remain useful for display, but they are poor keys for preview handoff because editors change them precisely when preview matters most.

A more reliable route design

Use a route like /api/preview?type=post&id=123&token=... or /preview/post/123. That route should validate the token, enable draft mode, look up the current slug or canonical path, and then redirect internally to the render route.

Also verify URL construction per environment:

• frontendSiteUrl matches the active deployment
• preview callbacks preserve protocol and base path
• branch or staging domains are not hardcoded away

A preview can route correctly and still collapse the moment the frontend loads. The usual cause is not WordPress itself, but browser cookie policy colliding with cross-domain auth.

If WordPress lives on cms.example.com and the frontend on www.example.com or preview.example.app, the browser may refuse to send or keep the cookie that marks draft mode. Common triggers include:

• cookies scoped to the wrong domain
• SameSite=Lax or Strict on a cross-site handoff
• missing Secure on HTTPS sites
• Safari and Chromium privacy features shortening or blocking third-party cookies
• serverless preview endpoints setting a cookie, then redirecting before it persists

The symptom looks like “preview worked for one request” or “redirected back to published content.” In practice, the preview token arrived, but the session did not survive the redirect chain.

Two common designs

Cookie-based draft mode feels seamless and supports multiple page loads, but it is fragile across domains, subdomains, and stricter browser settings.

Signed preview URLs put the proof in the URL itself, often with an expiry and HMAC or JWT signature. They avoid most cross-site cookie problems, but require careful TTLs, leak prevention, and cache bypass rules.

If the preview page renders correctly but shows only live content, the failure is usually not routing. The frontend reached a page; it fetched the wrong record. In headless setups, that often means a slug lookup returned the published post while the preview request needed a draft, autosave, or revision tied to a specific ID.

Check what the frontend is querying

A quick pattern check usually exposes the mismatch:

• Slug query: convenient for public pages, but commonly resolves to the published post only.
• ID query: better for preview, because the preview link usually carries a post ID and status context.
• Revision query: required when the CMS stores previewable changes in an autosave or revision object rather than the main post row.

If the request is anonymous, WordPress will often hide draft-state data even when the route itself is correct. Missing or stripped Authorization headers are a common cause, especially behind proxies, edge functions, or server actions.

WordPress API specifics

With the REST API, preview often depends on authenticated requests plus fetching the parent post’s latest autosave or revision. With WPGraphQL, preview usually relies on asPreview-style behavior or a dedicated resolver that swaps the published node for its preview version.

The key test is simple: compare the record ID, status, and modified content returned in preview mode against the published API response. If those payloads match, preview is not actually querying preview data.

A preview can load the correct record and still look broken because the frontend receives partial draft data. Missing blocks, empty custom fields, unresolved media, and vanished related items usually indicate a shape mismatch between what the renderer expects and what the API actually returns.

This is common in Gutenberg block preview problems. A block-based frontend often expects a normalized tree with parsed attributes, inner blocks, and server-rendered output for dynamic blocks. If preview fetches raw post_content but skips block parsing, render_block, or equivalent serializers, dynamic pieces such as query loops, embeds, and shortcodes disappear.

Custom fields fail differently. Many headless stacks read fields from the parent post, while the previewed values live in an autosave or revision. Field resolvers must be revision-aware; otherwise ACF, meta, or SEO fields silently fall back to published values.

Related content and media are often filtered by permissions:

• Attachments may require authenticated URLs or transformed image data unavailable in preview mode.
• Relationships to drafts or private posts may be excluded by capability checks.
• Resolvers may strip null or unauthorized nodes, breaking components that assume full arrays.

A reliable fix is to compare the published payload with the preview payload, field by field, then align serializers, revision lookups, and permission rules.

Check the deployed path

If preview survives locally but fails in production, environment drift is the usual culprit. Compare SITE_URL, preview origin, WordPress home/site URLs, and redirect rules. A link signed for staging.example.com often fails after a forced hop to www.example.com, especially when cookies or tokens are origin-bound.

Similar production-only failures appear when teams preview WordPress drafts in Astro, because static output can hide preview-state mistakes until deployment.

Then verify what changed between build time and request time:

• Secrets rotated in one service but not the other
• CDN or edge caches storing preview redirects, JSON, or Set-Cookie
• Static-first routes serving prebuilt HTML before draft mode bypasses cache

If the page updates only after a purge, application logic is usually intact; the broken piece is the cache key or cache policy.