Skip to main content
Contentstack MCP profile hub is in general availability!

Personalize variant returns the base entry, or null

•
10 min read

You set up an experience, the edge function runs, and the page still shows the default content. Or your middleware logs print null for every experience. Personalize has several hand-offs between the visitor and the rendered HTML, and a variant can get lost at each one.

This guide is for Next.js sites that resolve variants at the edge (Launch Edge Functions or Next.js middleware) and fetch entry variants with the TypeScript Delivery SDK. If you have not built that setup yet, start with Personalize with server-side rendering at the edge. This guide assumes it and only covers what goes wrong.

What you'll learn

  • How to find the step where a variant gets lost

  • Why localhost, QA and feature branches behave differently from production

  • What "does not belong to the Content Type" means and how to clear it

  • How the variant header cap and CDN caching hide variants

  • How to verify each step with curl

Symptoms

What you see

Most likely cause

Middleware logs show activeVariantShortUid: null for every experience, only on localhost

No public IP, so geolocation audiences never match

Error: Project not found: <uid> from Personalize.init()

Wrong or empty project UID in that environment

Error: Could not fetch manifest: 403 (or another status)

Something between your server and the Edge API blocks or rejects the call

Works locally, base content in QA

Environment variables, region URL or a firewall rule in QA

The Variant 'cs01f9918869240cb0' does not belong to the Content Type 'multi_teaser'

The entry or content type still points at a deleted variant

Variants work on main, base content on a feature branch

Entry variants are branch-specific and not cloned

Some experiences apply, others are ignored on the same entry

More aliases than the CDA merges in one request

The first visitor's variant shows up for everyone

Personalized HTML cached without the variant in the cache key

A change in the Personalize dashboard does not show up

Manifest propagation or a cached page

Why it happens

Contentstack concept: Personalize resolves a visitor in two separate systems. The Personalize Edge API evaluates audiences and returns a manifest: one active variant (or none) per experience. The Content Delivery API (CDA) then merges the matching entry variants onto the base entry, based on the aliases you send in the x-cs-variant-uid header.

That gives you four places where a variant can disappear:

  1. The manifest. The Edge API never picks a variant, because the visitor matches no audience or the call fails.

  2. The hand-off. The edge picks a variant, but the alias never reaches the Delivery SDK call.

  3. The CMS. The alias reaches the CDA, but no entry variant exists for it on that content type, branch or locale.

  4. The cache. Everything works, but a cached page or data cache serves somebody else's result.

Work through them in that order. How Personalize resolves variants explains the object model behind each step.

Fix it

Step 1: Log the manifest at the edge

Before you change anything, find out whether the Edge API picked a variant at all. getExperiences() returns every experience with its active variant:

const sdk = await Personalize.init(projectUid, { request });

console.log(JSON.stringify(sdk.getExperiences()));
// [{"shortUid":"a","activeVariantShortUid":"0"},{"shortUid":"b","activeVariantShortUid":null}]

console.log(sdk.getVariantParam());
// a_0

null means the visitor matched no variant in that experience. That is a valid result, not an error: the CDA returns the base entry, which is what an unmatched visitor should see. If the experience you care about is null, the problem is in the manifest. If it has a value and the page still shows base content, skip to step 4.

Step 2: Null variants on localhost

This usually happens when an audience uses a geolocation rule, such as "Country is Germany". Personalize derives location from the visitor's IP address. A request to localhost comes from a loopback address that maps to no country, so the visitor matches no country audience.

The Edge SDK forwards the incoming X-Forwarded-For header to the Edge API. To test a country rule locally, send a request that carries a public IP address from the target country:

curl -i http://localhost:3000/pricing \
  -H "X-Forwarded-For: <a public IP address in the target country>"

If the experience gets an active variant now, your setup is fine and only the test environment was wrong. For browser testing, deploy to a preview URL or expose your dev server with a tunnel such as ngrok, and use a VPN to test other countries.

Do not add a "pretend I'm in Germany" switch to production code. If you need to force an audience during development, give the audience a custom attribute rule as well and pass it with liveAttributes in development only.

Step 3: Works locally, fails in QA

The Edge API is public and needs no IP allowlisting, so a working local setup and a broken QA setup almost always differ in configuration. Check these in order:

  1. The project UID. Personalize.init() throws Project not found: <uid> when the UID is wrong. If it throws with an empty UID, the variable is missing. On Launch, edge functions read context.env, not process.env. In Next.js, NEXT_PUBLIC_ variables are inlined at build time, so adding one after the build changes nothing until you redeploy.

  2. The region. Outside AWS North America, call Personalize.setEdgeApiUrl() with your region's Edge API URL. The table is in Set up the Edge SDK.

  3. The network. Could not fetch manifest: 403 from a server you control usually means a firewall, WAF or bot rule in front of the outbound call. Call the manifest endpoint directly from the QA host:

curl -i "https://personalize-edge.contentstack.com/manifest" \
  -H "X-Project-Uid: $PERSONALIZE_PROJECT_UID"

A 200 with an experiences array means the platform side works and the problem is in your app's setup. A 404 with personalize.MANIFEST.PROJECT_NOT_FOUND means the UID or the region is wrong.

Step 4: The alias never reaches the CDA

If the manifest has a variant and the page shows base content, the request to the CDA did not carry the alias. The CDA returns base entries when there is no x-cs-variant-uid header. Common reasons:

  • One query passes .variants(aliases) and another does not. Headers, footers, listing pages and related-content calls are separate requests. Each needs the aliases.

  • The origin reads the wrong query parameter. If you passed customVariantQueryParam to init() at the edge, read that name on the origin too.

  • A rewrite or redirect between the edge and the origin drops the query string.

const variantParam = query[Personalize.VARIANT_QUERY_PARAM];
const aliases = variantParam
  ? Personalize.variantParamToVariantAliases(variantParam)
  : [];

console.log({ variantParam, aliases });
// { variantParam: 'a_0', aliases: [ 'cs_personalize_a_0' ] }

If aliases is empty here while the edge logged a value, the hand-off is broken. Fetch entry variants shows the full origin code.

Step 5: "The Variant … does not belong to the Content Type"

The full error looks like this:

The Variant 'cs01f9918869240cb0' does not belong to the Content Type 'multi_teaser'

This usually happens after variants were deleted and recreated, or after an entry with variants was copied. Recreated variants get new UIDs, and the entry or content type still points at the old ones.

  1. Open the content type and check which variant group it is linked to. If it points at a group that no longer exists, link it to the current group.

  2. Open the affected entry, clear the variant selection and select the current variants again.

  3. Save and publish the entry and its entry variants.

If the error survives that, create the entry again from scratch so it carries no stale variant references.

Step 6: Variants only work on main

Linked content types and entry variants are branch-specific, and they are not cloned when you create a branch. If you deliver from a feature branch or a branch alias that points to one, the CDA has no entry variants to merge and returns base entries.

Create and test entry variants on the branch you deliver from. If your release flow works with branches, plan for variants explicitly; Safe content model changes with branches and aliases covers that flow.

Step 7: Too many aliases in one request

Each request can merge only a small number of variants onto an entry. The entry variants limitations page lists 3 merged variants from the CDN; the CDA reference describes the cap as configurable. When a visitor qualifies for more experiences than the cap, the extra variants are not applied. Add show_errors=true to a CDA request to see the error:

{
  "code": "VARIANT_LIMIT_EXCEEDED",
  "message": "x-cs-variant-uid should not be greater than 5"
}

Keep the aliases in the order the SDK gives you. The first alias wins a field conflict, and the SDK lists experiences by priority. If you hit the cap, scope experiences with tags so a page only evaluates the experiences it can render. Layered and prioritized experiences explains tags and priority.

Step 8: A cached page serves the wrong variant

If personalized HTML is cached under a key that does not include the variants, the first visitor's result becomes everyone's. On Launch, the cache key includes the query string, which is why the edge function puts variants in the URL. Two setups break that:

  • A second CDN in front of Launch. The outer CDN caches the first response and never runs the edge function again. Send Cache-Control: no-store for personalized routes at that CDN, or let Launch be the only edge for personalized hostnames.

  • Your own data cache. If you wrap Delivery SDK calls in unstable_cache, a KV store or a memory map, the aliases must be part of the cache key.

Step 9: Changes do not show up yet

Changes to experiences take a moment to reach the manifest, and cached pages keep serving the old combination until they expire. The browser also keeps the cs-personalize-user-uid cookie, so an A/B test keeps you in the variant you were assigned. Before you decide something is broken, test in a private window and against a URL that is not cached yet.

Check that it worked

Call the CDA directly with the alias the edge logged, and compare it with a call without the header:

curl -s "https://cdn.contentstack.io/v3/content_types/page/entries?environment=production&include_publish_details=true&show_errors=true&query=%7B%22url%22%3A%22%2Fpricing%22%7D" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  -H "x-cs-variant-uid: cs_personalize_a_0" | jq '.entries[0] | {title, variants: .publish_details.variants}'

If the overridden fields differ from the base entry and publish_details.variants is filled, the CMS side works. Use your region's CDA host if your stack is not in AWS North America. Then load the page through the edge and confirm the rendered HTML matches that response.

Prevent it

  • Log getExperiences() and the resolved aliases at the edge, in development and behind a debug flag in production.

  • Build one helper that wraps every personalized Delivery SDK call, so no query can skip .variants(aliases).

  • Keep the project UID and the region's Edge API URL in the same environment variables in every environment, and check them at startup.

  • Keep variants on the branch you deliver from, and do not delete and recreate variants on live experiences.

  • Count how many experiences can apply to one entry, and keep that number under the merge cap.

Key takeaways

  • activeVariantShortUid: null means "no match", not "broken". Check audiences before code.

  • Localhost has no location. Send X-Forwarded-For with a public IP or test on a deployed URL.

  • Project not found means the UID or region is wrong for that environment.

  • No x-cs-variant-uid header means base content. Pass .variants(aliases) on every personalized call.

  • Entry variants are branch-specific, merges are capped, and cached HTML needs the variants in its cache key.

Frequently asked questions

  • Why does Personalize return null variants on localhost?

    Geolocation audiences need a public IP address. A request from localhost has none, so the visitor matches no country audience and the experience has no active variant.

  • Why does the CDA return the base entry even though the edge function resolved a variant?

    The alias never reached that request. Every Delivery SDK call that returns personalized content needs .variants(aliases), and without the x-cs-variant-uid header the CDA returns base entries.

  • Do entry variants exist on every branch?

    No. Linked content types and entry variants are branch-specific, and they are not cloned when you create a branch. Deliver personalized content from the branch where the entry variants were created.

  • How many variants can one CDA request merge?

    A small, plan-dependent number. The entry variants limitations page lists 3 merged variants from the CDN, so design layered experiences around that budget and check your plan before you rely on more.

  • Why does a change to an experience not show up right away?

    The manifest takes a moment to propagate, and cached pages keep serving the old variant until they expire or you revalidate. Test in a fresh session against an uncached URL.