Compass Web SDK: Nothing Renders?

Last updatedNov 2, 2026View as Markdown

An SDK-rendered Experience never shows a reader an error. It renders its content, or it renders nothing and collapses to zero height. That keeps a broken setup invisible to readers, but it also means a blank component looks the same whatever went wrong. Work through this checklist in order: each step is a gate the Experience must pass before the next one matters.

Start here

Turn on debug. Add debug: true to your init() options and reload. The SDK then logs why an Experience showed nothing. Remove it before you ship.
Open the browser console and the Network panel, and reload the page.

Find out which lifecycle event fired. Add this to the page, ahead of the Experience tag, so the listener exists before the event fires:

<script>
  ["rendered", "empty", "error"].forEach(function (name) {
    document.addEventListener("arc-compass:" + name, function (event) {
      console.log("arc-compass:" + name, event.target.localName);
    });
  });
</script>

Then use what fired to jump to the right step:

What you see	What it means	Go to
No lifecycle event at all	The Experience never asked for content: the SDK did not start, or consent is not granted.	1, 2
`arc-compass:error`	The Experience asked and the request failed.	3, 4
`arc-compass:empty`	The request succeeded and there was nothing to show.	5
`arc-compass:rendered`	The content is in the DOM. Check your own CSS for a hidden or zero-width container.	—

The events carry no detail. The reason a request failed appears only in the debug output, so read the console alongside the event.

SDK 1.2.0 and above also log a warning, without debug, for the two most common causes: an Experience tag on a page where init() never ran, and a page that never called setConsent(). The warning appears about three seconds after the page loads, at most once per page.

1. Is the SDK running?

An Experience tag is inert HTML until the SDK registers it. Check in the console:

customElements.get("arc-compass-recommendations-carousel"); // or the tag you used

undefined means the SDK never registered its elements. Check that:

The loader snippet is in <head> and the bundle request in the Network panel succeeds. A console error about the integrity attribute means the version in the URL and the integrity hash do not match: update both together (see Distribution). A Content Security Policy (CSP) error means your policy blocks the bundle’s host.
ArcCompass.init() runs on every page load, with both domain and apiKey.

SDK 1.2.0 and above log this warning:

ArcCompass SDK: <arc-compass-recommendations-carousel> will not render because init() has not run, threw, or could not load it. Call init() on every page load, then setConsent(true) or setConsent(false).

Experiences render behind the consent gate. Until setConsent(true) runs, an Experience makes no request and fires no lifecycle event, so it is silent rather than failed. Check that:

Your page calls setConsent on every page load. The SDK stores nothing between pages, so consent granted on the previous page does not carry over.
Your consent manager’s callback actually runs, and passes true. If the reader declined, or never answered the banner, the Experience correctly renders nothing.

SDK 1.2.0 and above log this warning when setConsent() was never called:

ArcCompass SDK: <arc-compass-recommendations-carousel> is waiting for consent: setConsent() has not been called. Call setConsent(true) on every page load.

A reader who declined gets no warning and no event, by design. If you reserve space for an Experience, collapse it yourself in that case (see Reserving space above the fold).

See Consent & Identity for the full consent state machine.

3. Does `site-id` resolve?

Every Experience request needs a Site, even on a single-site tenant. Check in the console:

document.querySelector('meta[name="arc-compass:site-id"]')?.content;

If that is empty and you do not pass siteId to init(), the Experience fires arc-compass:error without sending a request. With debug on, the console shows:

ArcCompass SDK: no `site_id` resolved for this page. Pass `siteId` to init(), or add <meta name="arc-compass:site-id" content="…"> to the page.

Each Experience requests once, when it mounts. If your app writes the meta tag after the tag mounts, call ArcCompass.refreshExperiences() after the tag is written.

arc-compass:item-id is not needed to render. The Experiences never send it; it drives the automatic page_view. A console warning that the automatic page_view was skipped is about events, not rendering, and is expected on a homepage or section front.

4. Is the request accepted?

In the Network panel, find the Experience request: its path contains /experiences/. With debug on, a failed request logs ArcCompass Recommendations: request failed; showing nothing. (or ArcCompass Catch-Up Card: …), with the cause beside it.

Network panel shows	Check
`401` or `403`	`apiKey` is a delivery token scoped to the browser events collection (the `collect-web` API). A key for another API, such as a `collector` (content-ingestion) key, is refused. See Provision a delivery token.
`404`, or a host you don’t recognize	`domain` is your org’s `collect-web/v1` base path, or `experiencesDomain` is set correctly if your Experiences are on a different host. See the Configuration reference.
A CORS error, or no response	The request was refused for this page’s origin. Confirm with your Arc XP representative that the origin you are testing from is allowed.
The request runs for five seconds, then fails	The Experience gives up after five seconds and does not retry. Reload to try again.

5. Is there anything to show?

arc-compass:empty is a successful answer, not a failure: the setup works and there was nothing for this reader. debug logs nothing for it.

Recommendations: the recommender had no results for this reader and surface.
Catch Up Card: Arc XP enables Catch Up per Site during provisioning, and until then the card renders nothing. A reader with nothing to catch up on also gets an empty card. Contact your Arc XP representative to confirm that Catch Up is enabled for the Site in site-id. If the tenant itself is not active, the request returns 403 and the card fires arc-compass:error instead.

Report a blank component in production

The lifecycle events bubble, so you can count blank Experiences in your own analytics without debug:

document.addEventListener("arc-compass:error", function (event) {
  yourAnalytics.track("compass_experience_error", { tag: event.target.localName });
});

onError in init() reports dropped events, not Experience failures.