# Troubleshoot Compass Recommendations

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

Diagnose refused requests, empty or generic recommendations, and missing events in Arc XP Compass.

Use this guide when Arc XP Compass recommendations aren’t behaving as expected on the data and API side. Most issues trace back to catalog sync, event volume, or cold-start behavior being misread as a bug.

> **Tip:**
> 
> **Using the Compass Web SDK and a component renders nothing?** Start with [Compass Web SDK: Nothing Renders?](https://dev.arcxp.com/content-recommendations/sdk/troubleshooting/), which walks through registration, consent, `site-id`, the delivery token, and the SDK’s lifecycle events. Come back here if the SDK checks pass but the data looks wrong.

## Find your symptom

| Symptom                                        | Go to                                                                                           |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| 401 or 403 from any Compass endpoint           | [Requests are refused](#requests-are-refused)                                                   |
| 422 from the Collector                         | [Requests are refused](#requests-are-refused)                                                   |
| 200 with an empty recommendations array        | [No recommendations returned](#no-recommendations-returned)                                     |
| Results feel random or generic                 | [Recommendations look low-relevance or generic](#recommendations-look-low-relevance-or-generic) |
| New readers or new stories get generic results | [New user or new content looks “cold”](#new-user-or-new-content-looks-cold)                     |
| Events are accepted but nothing improves       | [Events aren’t arriving or aren’t helping](#events-arent-arriving-or-arent-helping)             |
| The browser preflight fails                    | [The preflight returns 403 from the edge](#the-preflight-returns-403-from-the-edge)             |
| A pinned story is missing                      | [A pinned story isn’t showing](#a-pinned-story-isnt-showing)                                    |

## Requests are refused

| Status                                                                | Likely cause                                                                                                                          | Fix                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401                                                                   | The X-API-Key is missing, unknown, or not assigned to the right key collection.                                                       | Check that you are sending the right key for the API: **experiences** for recommendation reads, **collector** for content and server-side events. See [Verify the token](https://dev.arcxp.com/content-recommendations/content-recommendations-api-keys/#3-verify-the-token). |
| 403 on a recommendations read, body {"detail":"Tenant is not active"} | The key is valid, but the tenant is not servable (onboarding with no content yet, or suspended/pending/deleted).                      | See [Cold-start response states](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#cold-start-response-states).                                                                                                                      |
| 401 / 403 from the Collector                                          | Wrong X-API-Key, or the wrong host.                                                                                                   | Re-verify your key, that it was provisioned against the Collector API key collection, and the base URL with your Arc XP contact.                                                                                                                                              |
| 422 from the Collector                                                | The payload failed validation: a naive timestamp, an unknown event\_type, a bad enum, a missing required field, or an oversize field. | Read the response body; detail\[\*\].loc names the offending field. Fix the row or mapping and resubmit. Don’t retry as-is.                                                                                                                                                   |

For the full Collector status contract, including retries on `5xx` and `429`, see [Error and retry behavior](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/#error-and-retry-behavior).

## No recommendations returned

If the response comes back with an empty `recommendations` array, the model has nothing to rank for that user and site.

- **Check content ingestion first.** Query your CMS integration or webhook logs to confirm `POST /collector/v1/content` calls are succeeding. A model with no catalog cannot return anything. See [Verify the catalog](https://dev.arcxp.com/content-recommendations/content-recommendations-content-sync/#6-verify-the-catalog).
- **Confirm `site_id` matches.** The `site_id` on the recommendations request must exactly match the `site_id` used during content ingestion. A typo silently partitions your catalog into an empty sub-model.
- **Check for over-aggressive deletes.** If your CMS sends `action: "delete"` for items that are still live, the model excludes them from results. Audit your unpublish and delete pipeline.
- **Consider cold start.** The model needs a populated catalog and a meaningful behavioral signal before it returns ranked items. See the [Onboarding Checklist](https://dev.arcxp.com/content-recommendations/content-recommendations-onboarding-checklist/) for how to warm it up.

## Recommendations look low-relevance or generic

If the API returns results but they feel random or generic, the model likely doesn’t have enough behavioral signal yet.

- **Check event volume.** The model improves with more interactions. If you’re only sending `page_view` events, or only sending them for a small fraction of your traffic, personalization quality will be weak. Add richer event types (`click`, `article_save`, `deepest_scroll`, `engaged_read`) where appropriate.
- **Verify `user_id` consistency.** If the same person shows up under different `user_id` values across sessions, the model can’t accumulate history on them. Confirm your anonymization scheme produces stable IDs per user. See the [User ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/#user-id).
- **Check content metadata quality.** Missing `categories`, `tags`, or `author`values reduce what the model can reason about, especially for new content that has no engagement signal yet.

## New user or new content looks “cold”

Cold start is expected behavior, not a bug. See

[Cold Start and Model Warm-Up](https://dev.arcxp.com/content-recommendations/content-recommendations-cold-start/) 

for how the API handles it.

- **New or anonymous users** and **newly published content** are handled automatically, as described in that section.
- If you’re evaluating the API with a brand-new tenant, expect the first wave of results to look generic. Seed the model with historical content and a representative volume of events before drawing conclusions about relevance.

## Events aren’t arriving or aren’t helping

First, send a known test event and confirm the response, as described in [Verifying events are arriving](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/#verifying-events-are-arriving). Then use this table:

| Symptom                        | Likely cause                                       | Fix                                                                   |
| ------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------- |
| 422 on every event             | Bad envelope (naive timestamp, unknown event type) | Read the response body; fix your translation step.                    |
| 401 / 403                      | Wrong X-API-Key, or wrong host                     | Re-verify your key and the base URL with your Arc XP contact.         |
| 2xx but no recommendation lift | user\_id not stable, or events all dropped         | Confirm your translation step isn’t dropping every event.             |
| Recommendations feel stale     | Batch window too long, or a warehouse export       | Shorten buffering; enable streaming export instead of next-day batch. |

### Common pitfalls

- **Anonymous vs. identified users.** A login transition splits one reader into two IDs unless you stitch identity on your side. See the [User ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/#user-id) for the workable patterns.
- **Event de-duplication.** Retries must resend identical field values, including the original timestamp. See [\`event\_id\` and de-duplication](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/#event%5Fid-and-de-duplication).
- **Timestamp timezones.** Send timezone-aware ISO 8601 and the original interaction time, preferably in UTC. See [Timestamp conventions](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/#timestamp-conventions).
- **Batch size limits.** `/events/batch` accepts at most **100** events per request. Slice larger sets. A batch of 101 is rejected, not silently truncated.
- **`event_value` and `schema_version`.** `event_value` is a `0.0`–`1.0` ratio, and `schema_version` stays unset. See [The event envelope](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/#the-event-envelope).
- **Don’t force-fit events.** Drop events that don’t map to the Compass taxonomy rather than inventing an `event_type`, and never invent envelope fields outside the contract.

## The preflight returns `403` from the edge

CORS origins are provisioned at the platform edge. If your origin is not allowed and you cannot self-serve it, contact [Arc XP Client Support](https://support.arcpublishing.com/)with the exact origin you need allowed.

## A pinned story isn’t showing

**A pin reorders a story that recommendations were already able to serve; it does not inject one that the model didn’t surface.** When the reranker applies pins, it skips any pin whose story isn’t in the candidate set the recommender produced for that request. The recommender pulls more candidates than it returns, which leaves some headroom, but that headroom is finite.

In practice, this means a pinned story can be missing for a specific reader while appearing normally for others, because candidates are personalized per reader. Before assuming something is broken, check:

- **The website.** Pins are per website, and the Compass Admin UI scopes to the one selected in the left column.
- **The expiration.** An expired pin stops being applied silently.
- **Whether the story is a plausible recommendation at all.** A story that is not in the recommender’s catalog, or that the model never surfaces for the reader you’re testing with, will not be pinned into view. Very old stories and stories published moments ago are the usual suspects.
- **Whether the placement filters it out.** If the request scopes recommendations with `section` or `content_type`, a pinned story outside that section or type is never a candidate, for any reader. Filter values must match exactly.
- **Whether the story is also excluded.** Exclude takes precedence over pin. Exclude signals are set through the API, so they don’t show up in the Admin UI.
- **Whether you’re comparing like with like.** Pinning affects personalized recommendation lists. It does not reorder popular or trending responses.

For how pins work, see [Compass Admin UI: Editorial Controls](https://dev.arcxp.com/content-recommendations/content-recommendations-admin-ui-editorial-controls/).

## See also

- [Compass Web SDK: Nothing Renders?](https://dev.arcxp.com/content-recommendations/sdk/troubleshooting/) — SDK rendering issues.
- [Sync Your Content Catalog with Compass](https://dev.arcxp.com/content-recommendations/content-recommendations-content-sync/) — loading and verifying the catalog.
- [Provision and Manage Compass API Keys](https://dev.arcxp.com/content-recommendations/content-recommendations-api-keys/) — provisioning and verifying tokens.
- [Forward Events from a CDP or Server](https://dev.arcxp.com/content-recommendations/content-recommendations-cdp-integration/) — the event envelope and per-vendor recipes.
