Headless CMS preview links fail outside the office when they point to a private hostname, private IP address, or network-only environment. A headless CMS separates content editing from the front-end site, so the preview URL must be reachable from each editor's browser—not just from the CMS server. A link such as `http://cms-preview.local/article/example` may work on an office laptop but fail for a remote editor, client, or agency partner. The problem is usually hostname reachability, DNS resolution, or access controls rather than the content entry itself.
Official resources:
- Configure a secure CMS preview URL in Next.js — Verify that the preview link uses the deployed public domain and validates a secret before redirecting.
- Check whether a resolved IPv4 address is private — Compare the hostname’s resolved address with IANA’s special-purpose address registry.
Table of Contents
- What makes a hostname public or private?
- Why previews break in headless setups
- How to test the link from the right place
- Choose the access model before changing the URL
- Configuration details that often get missed
What makes a hostname public or private?
A public hostname resolves through public DNS and routes to a server accessible from the internet. For example, `preview.example.com` can be a public hostname if its DNS record and server firewall allow outside access. A private hostname works only within a defined network.
It may rely on office DNS, a VPN, a local hosts-file entry, or a non-routable address such as `10.x.x.x`, `192.168.x.x`, or `172.16.x.x` through `172.31.x.x`. The browser opening a preview link decides whether the hostname works. A cms can generate the correct URL and still send a remote editor to a destination their device cannot resolve or reach.
Why previews break in headless setups
In a traditional wordpress or Drupal site, the CMS often renders the preview itself. In a headless setup, the CMS usually passes a draft identifier, token, slug, or revision parameter to a separate front-end application.
That front end may run on an internal development server, a staging deployment, or a protected preview environment. If the CMS configuration uses an internal base URL, every preview link inherits that internal destination. Common failure patterns include:.
- The preview URL uses an office-only domain, such as `site.internal`.
- It points to `localhost`, which means the editor's own computer, not the developer's machine.
- It uses a private IP address available only on the company network.
- Public DNS exists, but a firewall, allowlist, VPN requirement, or single sign-on rule blocks the visitor.
- The front end accepts published pages but rejects draft-preview tokens or cookies.
How to test the link from the right place
Do not test only from the network where the site was built. Test with the same kind of device and connection used by the person reporting the failure. Start with the exact preview URL, not only the preview homepage.
Then check whether the hostname resolves, whether the browser reaches the server, and whether the draft content appears after access controls run. A practical test sequence is: If a public preview URL works on mobile data but not for one client, the issue may be the client's network policy or DNS filtering. If it fails everywhere outside the VPN, the hostname or access design is private by default.
- Open the link on an office connection.
- Open it on a mobile connection with Wi-Fi disabled.
- Open it from a remote worker's network or a VPN-disconnected test device.
- Confirm that the hostname resolves to the intended environment.
- Check the browser's error message: "server not found," timeout, certificate warning, login prompt, and blank draft page point to different causes.
Choose the access model before changing the URL
Use a publicly reachable preview hostname when outside reviewers need low-friction access. Protect it with unpredictable preview tokens, draft-only routes, expiration where available, and controls that prevent indexing. Use a private hostname when previews contain confidential launches, customer information, regulated material, or work that must remain inside a company network.
In that case, give every intended reviewer a supported path through VPN, identity access, or a secure sharing process. Do not expose an internal development server merely to make a preview link convenient. A safer pattern is a separately deployed preview environment, such as `preview.example.com`, with its own authentication and a front-end route that validates a short-lived preview token.
Configuration details that often get missed
Review the CMS preview URL template and the front-end application's environment variables together. WordPress preview integrations, Drupal decoupled preview modules, and custom CMS webhooks can each store the base URL in different places. Check for inconsistent values across development, staging, and production.
A deployment can publish a new front end while the CMS still generates links for an older internal hostname. Also verify the entire request path. A reachable hostname does not guarantee a useful preview if the front end loses the draft token during redirects, strips query parameters, caches the response, or requires a login cookie from another domain.
