How To: Troubleshooting Edge SSR

Use this article as a starting point when JSON-LD does not appear in the HTML source after deploying an edge worker, or when you see multiple Schema App data-source prefixes on the same page. It covers quick checks that apply to every CDN, then points you to the right guide for detailed troubleshooting.

For architecture and migration context, see Edge Rendering: What It Is, Why Use It, and How Schema App Delivers It.

TABLE OF CONTENTS

• Quick checks (all CDNs)
• Staging / pre-prod Cloudflare tests
• Staging / pre-prod Akamai tests
• Multiple Schema App sources on one page
• Where to go next
• Contact support

Quick checks (all CDNs)

Edge workers inject markup that already exists on Schema App's data CDN. They do not run the highlighter live at the edge. Before diving into CDN config, confirm:

1. Markup is authored in Schema App for the URL.
2. Crawler deployment is enabled (Highlighter templates) and crawls have completed.
3. Cache is populated — the URL has markup on data.schemaapp.com (or test/UAT equivalent).
4. Lookup URL matches — workers use origin + pathname (query/fragment stripped), not <link rel="canonical">. Check scheme, host (www vs apex), and account ID (including sub-accounts for pre-prod).
5. Worker is deployed and attached to the correct Akamai property or Cloudflare route.
6. Migration complete (if switching from JS) — highlight.js removed from production; Robots-Only disabled if previously enabled.

Most common cause of missing markup: no cached data for that URL. Fix cache population first, then troubleshoot CDN config.

Staging / pre-prod Cloudflare tests

When validating Cloudflare SSR on a development or staging hostname (for example development.example.com), use a dedicated Schema App project for that host and prove cache population before debugging Worker variables.

1. Separate project for the staging host. Create or use a sub-project whose pagesets/templates target the staging URLs (not production www). Production cache keys will not match staging hostnames.
2. Set SCHEMA_ACCOUNT_ID to the full path after schemaapp.com/db/. For a sub-project such as …/db/ParentAccount/StagingProject, the Worker variable is ParentAccount/StagingProject (not the parent account alone, and not only the short project name unless that is the true account id).
3. Confirm CDN cache for the staging URL. In Schema App Cache Tester (or Support), look up the exact staging URL under that account. Empty cache means the Worker will fail open and return unmodified HTML — this is expected, not a Cloudflare outage.
4. Populate cache with Crawler (recommended). Enable Crawler deployment on the staging templates and wait for crawls to finish. If the staging site’s robots.txt uses Disallow: / (common on pre-prod), allowlist Schema App’s crawler (SchemaBot) or temporarily relax disallow for the test paths so crawls can complete. Being able to open the page in a browser does not guarantee the crawler has written cache.
5. Optional short test via JavaScript cache. If you cannot crawl yet, a temporary JavaScript deployment (with highlight.js on the staging pages) can populate the highlighter cache path. Then set Cloudflare SCHEMA_FETCH_HIGHLIGHTER_CACHE = "true" for the test only. Prefer switching to Crawler + main cache path for the lasting setup.
6. Attach the Worker to the staging zone/route (for example *development.example.com/*). Cloudflare proxy alone does not inject markup.
7. Test with a matching User-Agent if SCHEMA_BOTS_ONLY = "true". Use SchemaBot or another token from SCHEMA_BOT_USER_AGENTS, and enable SCHEMA_DEBUG = true with wrangler tail to distinguish “no markup in cache” from “pass-through / not a bot”.

For full Cloudflare install steps, see Server Side Rendering — Cloudflare Setup Instructions.

Staging / pre-prod Akamai tests

Akamai Edge SSR on a staging hostname follows the same “prove cache first” rule as Cloudflare. Staging hosts are often locked down with Akamai Access Denied / IP allowlists, so crawls (and Cache Tester generation) can fail even when the EdgeWorker is installed.

1. Use a dedicated Schema App sub-project for the staging host (for example ParentAccount/StagingProject). Pagesets and templates must target the staging URLs; production host cache keys will not match.
2. Set EdgeWorker variables for the staging property:
   • PMUSER_SCHEMAAPP_ACCOUNT_ID = full account path (for example ParentAccount/StagingProject)
   • PMUSER_SCHEMAAPP_CDN_BASE_URL = staging scheme + host only (for example https://stg.example.com) — not data.schemaapp.com
   For multiple hosts on one property, use PMUSER_SCHEMAAPP_PROJECTS instead (see the Akamai setup guide).
3. Confirm CDN cache for the exact staging URL in Cache Tester under that account (main path and, if used, Highlighter JS). Empty cache → EdgeWorker fails open and returns origin HTML unchanged. This is expected.
4. Open the staging host to Schema App’s crawler before expecting cache. If the staging site returns Access Denied (Akamai 403) to public or SchemaBot requests, Schema App cannot crawl or generate markup for that URL. Ask the customer to allowlist:
   • Schema App crawler IP: 52.45.62.191
   • SchemaBot User-Agent: Mozilla/5.0 (compatible; SchemaBot/1.2; +https://www.schemaapp.com/bot/)
   See Allowlist Schema App IP Address & Endpoints. A temporary open of the test path for SchemaBot is enough for a proof.
5. Enable Crawler deployment on the staging templates after access works, then wait for the crawl (or ask Schema App support to kick a single-URL generation once access is confirmed).
6. Validate injection with a bot User-Agent once Cache Tester shows JSON-LD. Look for data-source="SchemaApp-Akamai:…" in View Source. Optionally set PMUSER_SCHEMAAPP_DEBUG=true and read X-SchemaApp-EW-Status (see the Akamai troubleshooting guide).

Note: Do not spend cycles on EdgeWorker Property Manager rules until Cache Tester returns markup for the staging URL under the staging account ID. Access Denied on the staging host blocks both normal crawls and one-off generation.

For full Akamai install steps, see Server Side Rendering — Akamai Setup Instructions and How-To: Troubleshoot Akamai Integration.

Multiple Schema App sources on one page

In View Source (or a bot User-Agent test), you may see more than one <script type="application/ld+json" data-source="…"> block from Schema App. Common prefixes:

• HighlightCrawl — cached markup from the main data CDN path (typical for Crawler deployment).
• JSCaching — cached markup from the Highlighter JS cache path (…/__highlighter_js/…). Appears when JavaScript deployment (or “fetch from highlight JS cache”) has populated that path, and the edge worker is configured to fetch the highlighter cache (Cloudflare: SCHEMA_FETCH_HIGHLIGHTER_CACHE = "true").
• HighlightJS — client-side injection from highlight.js still running in the browser (or a bot that executes JavaScript). This is not edge-injected HTML; it appears after the script runs.
• Editor — single-URL Editor data items. Expected alongside Highlighter markup when both apply to the same page.

Why HighlightCrawl and JSCaching appear together: The edge worker can inject both CDN paths when highlighter-cache fetch is enabled and both caches have data for the same URL. This is the same pattern seen when a project still has JavaScript-generated cache (or a second pageset) while also using Crawler. Prefer one generation path for SSR.

Recommended end state for edge SSR:

1. Highlighter templates on Crawler deployment; confirm crawls populate the main CDN path.
2. Edge worker injects from the main cache only (Cloudflare: leave SCHEMA_FETCH_HIGHLIGHTER_CACHE unset or "false" unless you intentionally need the JS cache path).
3. Remove highlight.js / window.schema_highlighter from production pages (and related tag-manager tags).
4. If stale JSCaching remains after switching to Crawler, ask Schema App support/engineering to clear the highlighter-cache objects for the affected templates/URLs (same class of cleanup as dual pageset cases).

Schema App does not recommend combining client-side JavaScript deployment with edge SSR for production. See Can I keep JavaScript deployment with SSR? and the internal CSM guide Switching Customers to Server-Side Rendering.

Bot-only tip (Cloudflare): If SCHEMA_BOTS_ONLY is enabled, test with a User-Agent that is on your SCHEMA_BOT_USER_AGENTS list. Include SchemaBot and your primary search crawlers (for example Googlebot) so validation and production crawlers both receive injection.

Where to go next

Note: Unlike Akamai's default bot-only Property Manager setup, Cloudflare Workers run on attached routes — human visitors may receive injected markup when cache data exists unless SCHEMA_BOTS_ONLY is enabled. This is expected, not a worker failure. See Bot vs human traffic in the Edge Rendering article.

Contact support

If you have confirmed cache is populated, the URL and account ID are correct, and the provider troubleshooting guides above do not resolve the issue, contact your Customer Success Manager or Schema App Support.

Helpful details to include:

• Schema App account ID and example URL
• CDN provider (Akamai or Cloudflare) and environment (staging vs production)
• Akamai: X-Schemaapp-Ew-Status header value from a bot-emulated request
• Cloudflare: wrangler tail output with SCHEMA_DEBUG = true
• Which data-source prefixes you see (HighlightCrawl, JSCaching, HighlightJS, Editor)
• Property Manager rule screenshots or Cloudflare route / Worker vars, if available