Troubleshoot Compass Recommendations
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.
Find your symptom
| Symptom | Go to |
|---|---|
401 or 403 from any Compass endpoint | Requests are refused |
422 from the Collector | Requests are refused |
200 with an empty recommendations array | No recommendations returned |
| Results feel random or generic | Recommendations look low-relevance or generic |
| New readers or new stories get generic results | New user or new content looks “cold” |
| Events are accepted but nothing improves | Events aren’t arriving or aren’t helping |
| The browser preflight fails | The preflight returns 403 from the edge |
| A pinned story is missing | A pinned story isn’t 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. |
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. |
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.
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/contentcalls are succeeding. A model with no catalog cannot return anything. See Verify the catalog. - Confirm
site_idmatches. Thesite_idon the recommendations request must exactly match thesite_idused 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 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_viewevents, 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_idconsistency. If the same person shows up under differentuser_idvalues across sessions, the model can’t accumulate history on them. Confirm your anonymization scheme produces stable IDs per user. See the User ID Guidance. - Check content metadata quality. Missing
categories,tags, orauthorvalues 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-Upfor 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. 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 for the workable patterns.
- Event de-duplication. Retries must resend identical field values, including the original timestamp. See `event_id` and de-duplication.
- Timestamp timezones. Send timezone-aware ISO 8601 and the original interaction time, preferably in UTC. See Timestamp conventions.
- Batch size limits.
/events/batchaccepts at most 100 events per request. Slice larger sets. A batch of 101 is rejected, not silently truncated. event_valueandschema_version.event_valueis a0.0–1.0ratio, andschema_versionstays unset. See 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 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
sectionorcontent_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.
See also
- Compass Web SDK: Nothing Renders? — SDK rendering issues.
- Sync Your Content Catalog with Compass — loading and verifying the catalog.
- Provision and Manage Compass API Keys — provisioning and verifying tokens.
- Forward Events from a CDP or Server — the event envelope and per-vendor recipes.