# Compass Web SDK: Nothing Renders?

Source: https://dev.arcxp.com/content-recommendations/sdk/troubleshooting/

Diagnose a blank arc-compass-recommendations-carousel, arc-compass-recommendations-list, or arc-compass-catchup-card: a checklist for registration, consent, site-id, the delivery token, and Catch Up enablement, and how to read the arc-compass:empty and arc-compass:error events.

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

1. **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.
2. **Open the browser console and the Network panel**, and reload the page.
3. **Find out which lifecycle event fired.** Add this to the page, ahead of the Experience tag, so the listener exists before the event fires:  
```html
<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](#1-is-the-sdk-running), [2](#2-is-consent-granted-on-this-page-load) |
| arc-compass:error         | The Experience asked and the request failed.                                              | [3](#3-does-site-id-resolve), [4](#4-is-the-request-accepted)            |
| arc-compass:empty         | The request succeeded and there was nothing to show.                                      | [5](#5-is-there-anything-to-show)                                        |
| 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:

```js
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](https://dev.arcxp.com/content-recommendations/sdk/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).
```

## 2\. Is consent granted on this page load?

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](https://dev.arcxp.com/content-recommendations/sdk/recommendations-components/#reserving-space-above-the-fold)).

See [Consent & Identity](https://dev.arcxp.com/content-recommendations/sdk/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:

```js
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](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/#1-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](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/#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`:

```js
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.

## See also

- [Compass Web SDK: Integration Guide](https://dev.arcxp.com/content-recommendations/sdk/integration-guide/) — the full setup each Experience depends on.
- [Recommendations Components: Loading, empty, and error](https://dev.arcxp.com/content-recommendations/sdk/recommendations-components/#loading-empty-and-error)
- [Catch Up Card: Lifecycle and reserving space](https://dev.arcxp.com/content-recommendations/sdk/catch-up-card/#lifecycle-and-reserving-space)
- [Compass Web SDK: Consent & Identity](https://dev.arcxp.com/content-recommendations/sdk/consent-identity/)