Contentful preview failures usually come from one mismatched layer: the site cannot be reached, the preview URL points to the wrong route, the app uses the Delivery API instead of the Preview API, the token lacks access, or Live Preview is blocked by iframe security headers. Identify the failing layer first, then apply the corresponding fix.
Start with the symptom
Test the configured preview URL in a normal browser tab before changing application code. Then test the same URL in Contentful’s Live Preview or Experiences canvas. Record the final URL (with secrets removed), HTTP status, browser console error, Network-panel response headers, Contentful environment ID, and whether the problem occurs only inside the embedded pane.
| Symptom | Most likely layer | First check |
|---|---|---|
| Browser cannot reach the page | Server, port or preview URL | Confirm the frontend is running and the configured URL uses the correct host and port. |
| “Your website refused to connect” in the canvas | Server availability or iframe policy | Open the URL directly, then inspect X-Frame-Options and Content-Security-Policy. |
| Published content appears instead of drafts | API host, token or data-loading path | Verify the Preview API host and preview token are used together. |
| 404 for an entry you can see in Contentful | Permissions, environment or route | Check token access and the environment in the request, not only the entry ID. |
| Wrong page or locale | Preview URL template and field values | Validate slug, locale and environment tokens against the frontend route. |
Fix the Preview API host and token
Draft-capable requests must use Contentful’s Content Preview API (CPA), not the Content Delivery API (CDA). Replace https://cdn.contentful.com with https://preview.contentful.com and use a matching preview access token. Changing only the hostname or only the token creates a mismatch; production delivery tokens do not work with the Preview API. Contentful customers with EU data residency should use https://preview.eu.contentful.com. The Preview API documentation describes a default limit of 14 requests per second and the X-Contentful-RateLimit-Reset response header for retry timing.
Send the token as a bearer header
Use an Authorization: Bearer header rather than putting credentials in a URL. Contentful’s setup guide explicitly warns: “For security reasons, never include an access token in the preview URL.” Keep the token server-side or in protected environment variables; do not expose it in a client-rendered link.
#1 Best Overall
curl "https://preview.contentful.com/spaces/SPACE_ID/environments/ENVIRONMENT_ID/entries/ENTRY_ID"
-H "Authorization: Bearer CONTENT_PREVIEW_TOKEN"Use the environment path supported by your client or SDK. Confirm that SPACE_ID, ENVIRONMENT_ID and ENTRY_ID belong together. A valid token without access to the requested resource can produce 404, so treat a 404 as an authorization or environment problem as well as a missing-entry problem.
Check the preview URL and route template
In Contentful, open the preview configuration for the relevant platform and content types. Confirm that the URL template resolves to a real route in the deployed frontend. The setup supports tokens for environment ID, entry ID, slug, locale and linked entries or fields. Compare the resolved URL with a manually opened route.
Environment and master configuration
Setup is configured in the master environment. To preview entries in another environment, the underlying content type must exist in master. Ensure the request and URL template select the intended environment rather than silently falling back to a production default.
Slug and locale values
Validate every field used to build a URL. Encode spaces, question marks, slashes and other unsafe characters; ideally generate routes from a controlled slug field. A localized slug token with an invalid locale does not fall back to the default locale, so verify that the locale code exists on the entry and is enabled in the space. Check whether your frontend expects a locale prefix such as /en/ while the template produces /.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Make Live Preview embeddable
A page can work perfectly in a new tab yet fail in Live Preview because the editor loads it in an iframe. Inspect the document request in your browser’s Network panel and review response headers.
Remove or adjust framing restrictions
- Remove
X-Frame-Options: DENYorSAMEORIGINfrom the preview response. - If you use Content-Security-Policy, include
frame-ancestors https://app.contentful.com. - Apply these rules to the preview host or preview route without weakening unrelated production security policy.
Contentful identifies these headers as causes of connection refusal. SSO cannot work when embedding is disallowed.
Allow authentication cookies in the iframe
If preview authentication depends on cookies, set the documented attributes SameSite=None and Secure. The site must be served over HTTPS for a Secure cookie. Browser privacy settings or third-party-cookie restrictions can still prevent a session from being available inside the editor; verify the request’s Cookie header and the browser’s cookie warnings.
Verify how the app loads data
The Preview API does not implement Contentful’s Sync API. An application that relies exclusively on Sync API data cannot provide a working preview through CPA. Add a preview-specific request path using CPA, or use a client configuration that selects CPA whenever preview mode is enabled.
Inspect the response, not just the page
- 401 or 403: token is missing, invalid or not permitted; create or select the correct preview credential and check environment access.
- 404: entry, environment or route may be wrong; a token lacking access can also yield 404.
- 429: requests exceed the documented default of 14 per second. Read
X-Contentful-RateLimit-Reset, wait that interval, then retry with backoff. - 200 with published values: inspect the host, token and any caching layer. A production CDA request or cached response will not show drafts.
- 200 with missing linked data: verify includes, linked-entry permissions and the environment containing those references.
Use a controlled troubleshooting sequence
- Open the exact resolved preview URL in a private browser window. Confirm DNS, HTTPS, host and port.
- Open DevTools and capture the document status, console error and response headers.
- Check that the app’s preview flag selects
preview.contentful.com(or the EU host) and a Preview API token. - Verify the token’s environment and resource permissions. Never paste the token into the URL or a screenshot.
- Compare the preview URL’s slug, locale and entry ID with the actual entry fields and frontend routes.
- Test a direct CPA request. If it fails, fix Contentful access before debugging rendering.
- Test the page in Live Preview. If only the iframe fails, correct X-Frame-Options, CSP and cookie attributes.
- Check for Sync API-only code and add a CPA data-loading branch.
- When you see 429, stop rapid retries and honor the reset header with exponential backoff.
Or skip the browser setup
For a clean diagnostic image of the resolved preview URL, ScreenshotNeo can load the page without you maintaining a headless-browser script. Its cleanup accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result.
Use the API documentation at https://screenshotneo.com/docs/ for options such as a custom viewport, full-page capture, waits, headers, cookies and an Authorization value. This example captures a preview route; keep credentials out of the URL and pass any required site authentication through the documented header or cookie options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/preview/article -o shot.webpThe same request in Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com/preview/article"}, timeout=90)
open("shot.webp", "wb").write(r.content)And Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com/preview/article' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Reliability and cost considerations
- Keep preview credentials server-side and rotate them if exposed.
- Do not cache draft responses as public production content. Separate preview cache keys by environment, locale and entry.
- Use bounded retries for 429 responses and log the reset delay.
- When diagnosing iframe issues, compare the same URL in a tab and in Live Preview; that isolates embedding policy from application behavior.
- Capture a reproducible request with secrets removed before changing framework code.
What to include when escalating
Provide Contentful support or your platform team with the redacted preview URL, status code, response headers, browser console message, space and environment IDs, content type, locale, and whether the failure is new-tab-only, embedded-only or present in both. Include whether the direct CPA request succeeds and whether the application uses Sync API. This evidence identifies the failing layer without disclosing an access token.
Recommended Free Tools
Frequently Asked Questions
Does a Contentful preview token work with the Delivery API?
No. Draft requests require the Content Preview API host and a matching preview access token.
Best Value
Why does Live Preview fail while the URL works in a tab?
The embedded request may be blocked by X-Frame-Options or Content-Security-Policy, or its authentication cookie may lack SameSite=None and Secure.
Can a 404 mean the entry exists?
Yes. Contentful documents that a token without access to a resource can return 404, so check permissions and environment as well as the entry ID.
What should I do after a 429 response?
Wait according to X-Contentful-RateLimit-Reset and retry with backoff instead of sending immediate repeated requests.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
