Skip to content

Troubleshoot Compass Recommendations

Last updatedView as Markdown

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

SymptomGo to
401 or 403 from any Compass endpointRequests are refused
422 from the CollectorRequests are refused
200 with an empty recommendations arrayNo recommendations returned
Results feel random or genericRecommendations look low-relevance or generic
New readers or new stories get generic resultsNew user or new content looks “cold”
Events are accepted but nothing improvesEvents aren’t arriving or aren’t helping
The browser preflight failsThe preflight returns 403 from the edge
A pinned story is missingA pinned story isn’t showing

Requests are refused

StatusLikely causeFix
401The 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 CollectorWrong 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 CollectorThe 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/content calls are succeeding. A model with no catalog cannot return anything. See 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 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.
  • 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

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. Then use this table:

SymptomLikely causeFix
422 on every eventBad envelope (naive timestamp, unknown event type)Read the response body; fix your translation step.
401 / 403Wrong X-API-Key, or wrong hostRe-verify your key and the base URL with your Arc XP contact.
2xx but no recommendation liftuser_id not stable, or events all droppedConfirm your translation step isn’t dropping every event.
Recommendations feel staleBatch window too long, or a warehouse exportShorten 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/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.
  • 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 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.

See also