2.x
  1. Troubleshooting

Troubleshooting personalization and tracking events

If personalized pages don't render as expected or SitecoreAI analytics doesn't show the expected data, troubleshoot your application's personalization and tracking configuration.

This topic covers Content SDK 2.x Next.js applications. Personalization runs on the server through PersonalizeProxy. For real visitors, page view events run in the browser through the @sitecore-content-sdk/events package.

Verify personalization and tracking setup

Before troubleshooting requests, verify the following settings:

  1. Connect the application to the correct SitecoreAI environment and site. Verify the server context ID (SITECORE_EDGE_CONTEXT_ID) and client context ID (NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID). Use the Live context when testing published content on the public site. See Connect your Content SDK app to SitecoreAI.
  2. Assign an analytics identifier to the site and each language you want to track or personalize. Adding a language doesn't automatically assign an analytics identifier. See Manage personalization and analytics for sites.
  3. Publish the page and its personalized variants. Verify that the visitor meets the audience conditions for the variant you expect to display.
  4. In src/proxy.ts, verify that the proxy chain includes PersonalizeProxy and passes it the sites list from .sitecore/sites.json, scConfig.api.edge, and scConfig.personalize. Run it after MultisiteProxy (Pages Router) or AppRouterMultisiteProxy (App Router). For App Router applications, LocaleProxy must also run before personalization. Personalization uses the site and language these proxies resolve. Ensure that the proxy matcher includes the page you are testing and that any custom skip callback returns false for the request.
  5. Verify that browser initialization includes analyticsPlugin with analyticsBrowserAdapter() and eventsPlugin(). In starter applications, this initialization is in src/Bootstrap.tsx. See Initializing tracking, events, and personalization in the Content SDK.
  6. Verify that the application renders CdpPageView and that your cookie consent implementation permits tracking for the test visitor.
Note

Starter applications disable personalization and browser page view tracking in development mode. They also skip browser tracking in editing and preview modes. Test published content in normal rendering mode using a production build connected to SitecoreAI. PersonalizeProxy requires Experience Edge configuration and can't use local container API endpoints for personalization.

Personalized page rendering issues

The personalization proxy retrieves variant information from Experience Edge, then requests a personalization decision. If a request times out, the visitor sees the default page.

To troubleshoot the personalization proxy:

  1. Enable debug logging by setting the following environment variable:

    DEBUG=content-sdk:personalize
  2. Restart the application, request the page, and inspect the server logs. Check the resolved site, language, request path, and any messages indicating that the proxy skipped the request.

  3. Verify that the context IDs match the environment you are testing. Verify that NEXT_PUBLIC_PERSONALIZE_SCOPE matches the PAGES_PERSONALIZE_SCOPE environment variable in the connected SitecoreAI environment. Starter applications use the same configured scope for server-side personalization and browser page view events.

  4. Check for timeout errors before interpreting a skip message. An Experience Edge timeout produces a GraphQL client response error log containing [IE-003] Timeout exceeded immediately before skipped (personalize info not found). For this error, adjust PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT as described in Configure personalization timeouts. For Sitecore CDP personalization timeouts, adjust PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT.

Configure personalization timeouts

You can configure timeouts through environment variables or the personalize properties in sitecore.config.ts.

Environment variableConfiguration propertyDescriptionDefault
PERSONALIZE_MIDDLEWARE_CDP_TIMEOUTpersonalize.cdpTimeoutTimeout for Sitecore CDP personalization requests, in milliseconds.400
PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUTpersonalize.edgeTimeoutTimeout for Experience Edge requests that retrieve personalization information, in milliseconds.400

For example, to set a one-second timeout for each request, add the following values to your rendering host's environment configuration:

PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT=1000
PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT=1000

If you explicitly set personalize.cdpTimeout or personalize.edgeTimeout in sitecore.config.ts, those values take precedence over the corresponding environment variables. Update or remove the explicit values before testing an environment variable change. See The Sitecore configuration file.

Restart or redeploy the application after changing its configuration. Request the page again and review the logs to verify that the request completes within the new timeout.

Important

Both timeout values use milliseconds. Increasing a timeout gives a request more time to complete, but can increase page response time. Adjust the value for the failing request based on the timings in your logs.

Personalization is skipped or the default variant appears

The default variant doesn't always indicate a timeout. Use the debug logs to identify the cause:

Log messageWhat to check
personalize proxy is disabled globallyVerify personalize.enabled in sitecore.config.ts. It defaults to false in development mode.
personalize service not configured - edge config requiredVerify that the application has Experience Edge context IDs configured.
personalize info not foundFirst check the preceding log for response error containing [IE-003] Timeout exceeded. If present, follow Configure personalization timeouts to adjust the Experience Edge timeout. Otherwise, verify the requested site, route, language, and published content.
no personalization configuredVerify that the published page contains personalization variants.
no variant(s) identifiedVerify audience conditions and that the personalization scope matches the connected SitecoreAI environment. For geolocation conditions, implement extractGeoDataCb in the PersonalizeProxy configuration in src/proxy.ts to supply the visitor's city, country, or region. The starter example is commented out; the proxy sends geolocation data only when the callback supplies it.
preview, prefetch, or bot requestTest a normal page visit in a browser. The proxy skips these requests by design.

Bot detection is available from Content SDK 2.1.0. When enabled, it skips personalization for bot traffic by default. See Lightweight tracking.

Missing or unexpected analytics data

To troubleshoot browser page view events:

  1. Open the browser developer tools. Check the console for initialization errors and the Network tab for failed event requests. Inspect the response for details about the failure. For SDK error codes, see Troubleshooting.

  2. Verify that NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID belongs to the environment you are testing and that browser initialization uses the correct site name. Rebuild and redeploy the Next.js application after changing public environment variables.

  3. Inspect the browser SDK configuration in the console:

    window.scContentSDK?.analytics_core?.options
    window.scContentSDK?.analytics_core?.getClientId()
    window.scContentSDK?.analytics_core?.version
    window.scContentSDK?.events?.version

    These values show the analytics configuration, current client ID, and analytics and events library versions. eventsPlugin sets events.version independently of the analytics diagnostic properties. Use it to check whether browser initialization reached eventsPlugin; its presence doesn't confirm that analytics initialization succeeded.

    If analytics_core is missing, check the following causes:

    • Browser initialization didn't run, or failed before analyticsPlugin completed initialization.
    • analyticsPlugin has options.enableCookie set to false. It returns before setting the analytics diagnostic properties.
    • The client ID request failed. If Edge returns no client ID, initialization throws [IE-005]. Check the browser console and Network tab for the failed request.
  4. If your application enables cookie-based tracking, check that the browser stores the sc_cid cookie. Verify the configured cookie domain and whether the visitor's consent settings permit tracking.

  5. Verify that CdpPageView receives route data and uses the page's variant ID, language, and configured personalization scope when creating pageVariantId.

  6. Check that the analytics dashboard covers the correct site, analytics identifier, and date range. Sites or languages that share an analytics identifier can share analytics data.

If you have suggestions for improving this article, let us know!