Contentful preview failures usually come from one mismatched layer: the preview site is unreachable, the preview URL points to the wrong route, the app uses the Delivery API instead of the Preview API, the token cannot read the requested environment, or Live Preview is blocked by iframe security headers. Identify the failing layer first, then apply the matching fix below.
Start by identifying the symptom
Test the configured preview URL in a normal browser tab before changing application code. Then compare that result with the behavior inside Contentful.
| Symptom | Most likely layer | First check |
|---|---|---|
| The page will not open anywhere | Server, port, URL or deployment | Open the exact preview URL directly and inspect the HTTP response. |
| The page opens but shows published content | API host, token or data-loading path | Confirm the app uses the Preview API host and a preview token. |
| An entry is missing or returns 404 | Environment, permissions, route fields or entry ID | Check token access, environment ID, locale and the generated route. |
| It works in a tab but says “refused to connect” in Live Preview | Iframe policy or cookies | Inspect X-Frame-Options, CSP and cookie attributes. |
| Requests intermittently fail with 429 | Preview API rate limiting | Honor X-Contentful-RateLimit-Reset before retrying. |
Contentful distinguishes Preview in new tab from Live Preview. The new-tab mode mainly tests your URL, server, route and data path. Live Preview adds iframe embedding and browser cookie rules, so a page can work in a tab and still fail in the editor pane.
1. Verify that the preview server and URL are reachable
Check the process and port
Run the frontend locally or confirm that the deployed preview service is healthy. If your app listens on a nonstandard port, the Contentful preview URL must include that port. Open the full URL outside Contentful; a refused connection, DNS error or timeout is a hosting problem rather than a Contentful entry problem.
#1 Best Overall
- Confirm the development server is running and bound to an address reachable from the browser.
- Check that the configured protocol (
httporhttps), hostname, port and path are correct. - If Contentful is hosted remotely while your app runs on localhost, expose the app through a reachable HTTPS tunnel or use a deployed preview environment.
- Look at the browser Network panel for the initial document response, redirects and failed subrequests.
Test the URL template
Copy the URL generated by Contentful, remove any secrets, and open it directly. A template that produces /undefined, an empty slug or the wrong content-type route will fail even when the site itself is healthy. Compare the generated path with a route that you know exists in the frontend.
2. Use the Content Preview API, not the Delivery API
The Content Preview API (CPA) is the draft-capable counterpart to the Content Delivery API (CDA). For ordinary REST requests, replace https://cdn.contentful.com with https://preview.contentful.com and use the matching preview access token. A production delivery token does not authenticate against the Preview API. Customers with EU data residency use https://preview.eu.contentful.com.
Minimal REST request
curl "https://preview.contentful.com/spaces/SPACE_ID/environments/ENVIRONMENT_ID/entries/ENTRY_ID"
-H "Authorization: Bearer PREVIEW_ACCESS_TOKEN"Keep the token in the Authorization header. Contentful explicitly warns: “For security reasons, never include an access token in the preview URL.” Do not put it in a query string, route token or client-visible link.
Check the host and credential as a pair
- Preview host plus preview token: draft-capable request.
- Delivery host plus delivery token: published-content request.
- Preview host plus delivery token: authentication failure or unusable preview request.
If your application chooses its API client from an environment variable, print the selected host (never the token) in a development log. A common deployment mistake is setting the preview URL but leaving the production API host or token in the preview environment.
3. Check token permissions and environment access
A syntactically valid token can still lack access to the requested resource. Contentful notes that an unauthorized resource may appear as a 404, so do not assume every 404 means the entry was deleted.
- Confirm the token belongs to the same space as the entry.
- Confirm the request names the intended environment.
- Verify that the token is a preview token and that its permissions include the environment and resources being requested.
- Compare the entry ID and content type with the record selected in Contentful.
Capture the request URL with the token removed, the status code, space and environment identifiers, and the exact entry ID. Those details let an administrator distinguish a missing entry from an access problem without exposing credentials.
4. Correct the preview platform and route configuration
Review the platform settings
In the Contentful web app, open the preview configuration, confirm the selected preview platform, and check which content types use it. Setup is configured in the master environment. To preview entries in another environment, the underlying content type must exist in master.
Validate every URL token
Contentful’s setup supports tokens for values such as environment ID, entry ID, slug, locale and linked entries or fields. Make sure the template uses the field that actually determines the frontend route.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Entry ID: useful for a route that loads by ID rather than slug.
- Slug: verify the field is populated and matches the frontend’s routing rules.
- Locale: ensure the locale exists and is supported by the entry and site.
- Environment ID: ensure the frontend requests the same environment named in the URL.
- Linked fields: confirm the linked value is present before using it in a path.
A localized slug token with an invalid locale does not fall back to the default locale. Also validate values used in URLs for unsafe characters. Encode or normalize them according to your framework’s routing rules instead of concatenating arbitrary field text into a path.
Check route behavior independently
Take the generated path and replace its data-loading call with a known test entry, or inspect the server log for the resolved route. If the path is correct but the page is blank, continue to the API and rendering checks; if the path is wrong, fix the Contentful template or the frontend route before changing credentials.
5. Fix Live Preview iframe security
Live Preview embeds your site in an iframe. Inspect the document response headers in the browser Network panel while opening the embedded preview.
Remove conflicting frame protection
Contentful says to remove X-Frame-Options or configure your Content Security Policy with frame-ancestors https://app.contentful.com. A page can be perfectly functional as a top-level document and still be refused inside the editor when either policy blocks framing.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallContent-Security-Policy: frame-ancestors 'self' https://app.contentful.com;Apply the policy at the layer that serves the HTML response: CDN, reverse proxy, hosting platform or application server. Check the final response in production, because a proxy can add a header after your framework sets one.
Allow cookies needed by the preview session
If authentication depends on cookies inside the iframe, use the documented SameSite=None and Secure attributes. Without them, the browser may omit the session cookie in the embedded context. SSO will not work if the site disallows embedding in the first place.
6. Check how the app loads data
The Preview API does not implement the Sync API. An application that relies exclusively on Sync API data cannot use that path for preview. Add a preview-specific request path that queries the Preview API, or otherwise provide a data-loading method supported by the preview environment.
Inspect the actual response
- Use the Network panel to verify the request host is
preview.contentful.com(orpreview.eu.contentful.comfor EU data residency). - Check that the Authorization header is present on server-side requests and is not exposed in browser URLs.
- Confirm draft fields are present in the response your renderer receives.
- Look for a server-side exception that turns a valid API response into a blank page.
7. Handle rate limits and retries
Contentful’s documented default Preview API rate limit is 14 requests per second (the documentation does not state a year for this figure). A 429 response means the client should slow down. Read X-Contentful-RateLimit-Reset and wait for the indicated reset interval before retrying.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsBest Value
- Do not retry a 401 or 403 immediately; fix the host, token or permission.
- Do not retry a deterministic 404 without checking environment, ID and access.
- For 429 responses, use bounded exponential backoff and respect the reset header.
- Cache stable content during a preview session instead of issuing duplicate requests for every component.
8. A practical diagnostic sequence
- Open the exact generated preview URL in a normal browser tab.
- Record the document status, redirect chain and console error.
- Check the URL’s host, port, path, locale and environment values.
- Inspect the data request and confirm the Preview API host and preview token.
- Check token access when a request returns 404, not only when it returns 401 or 403.
- Verify the content type exists in master and that the selected environment is available to the token.
- For embedded-only failures, inspect
X-Frame-Options, CSPframe-ancestorsand cookie attributes. - Check for Sync API-only code and replace it with a Preview API-compatible path.
- If the response is 429, wait according to
X-Contentful-RateLimit-Resetand reduce request bursts.
Or skip the browser setup
If you need a rendered capture of the preview URL for a ticket, regression check or review, ScreenshotNeo can take the shot with one request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://your-preview-site.example.com -o preview.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://your-preview-site.example.com"}, timeout=90)
r.raise_for_status()
open("preview.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://your-preview-site.example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
require('fs').writeFileSync('preview.webp', Buffer.from(await res.arrayBuffer()));See the ScreenshotNeo documentation for options such as full-page capture, a CSS-selector element, custom headers and cookies, waiting for a selector or network idle, custom JavaScript, dark mode, device presets, PDFs, caching, signed links, asynchronous jobs and bulk capture of up to 100 URLs per call. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account to capture your preview page.
When to escalate
Ask for help only after collecting reproducible evidence: the generated URL with secrets removed, HTTP status, browser console and Network errors, space and environment IDs, entry ID, locale, and whether the failure occurs only in Live Preview. This separates a route defect from an access, hosting or iframe-policy defect and prevents unsafe credential sharing.
Frequently Asked Questions
Why does a Contentful preview URL show published content?
The app is usually calling the Delivery API or using a delivery token. Preview requests require the Preview API host and matching preview access token.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Can a 404 mean that my Contentful entry exists?
Yes. A token without access to the requested resource can produce a 404, so verify environment permissions and token scope as well as the entry ID.
Why does the site work in a tab but not in Live Preview?
Live Preview adds iframe restrictions and cookie rules. Check X-Frame-Options, CSP frame-ancestors and SameSite=None; Secure cookies.
Does the Contentful Preview API support Sync API requests?
No. An application that depends exclusively on Sync API needs a different preview data-loading path.
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.
Recommended Free Tools
