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

Nested references come back empty, or fail with error 141

•
9 min read

A page renders without its author, a card list is empty, or the whole request fails with 422 and error_code: 141. The entry is there in the CMS, the references are filled in, and the response still does not contain them.

This usually happens on pages built from modular blocks, global fields and references, fetched with the TypeScript Delivery SDK or the Content Delivery API (CDA) from a server, a static build or a Live Preview session. The causes are few, and each leaves a different trace in the response.

What you'll learn

  • How to recognize each cause from what the response looks like

  • How to write include[] paths that match your schema, including blocks and global fields

  • Where the depth and include limits are, and what happens when you cross them

  • How publish state and locale affect resolved references

  • How to model content so pages do not need deep reference chains

Symptoms

What you see

Likely cause

The reference field holds [{ "uid": "blt...", "_content_type_uid": "author" }]

The path was not included

The field is resolved at level one, but nested references are still bare UIDs

include_all without a depth, or a nested path missing from include[]

A multiple reference field returns fewer items than the editor selected

Some referenced entries are not published to that environment or locale

A reference inside a modular block or global field is never resolved

The include path skips a block UID or uses the wrong global field UID

422 with "error_code": 141 and "Failed to fetch entries. Please try again with valid parameters."

The API rejected a parameter, for example a depth or include count over the limit

422 with "error_code": 141 and "The requested object doesn't exist."

The entry you fetched by UID is not published in that environment and locale

414 URI Too Long

Too many or too long include paths in the URL

Why it happens

Contentstack concept: A Reference field stores pairs of uid and _content_type_uid. The referenced entry is a separate entry with its own versions, its own localized copies and its own publish state per environment and locale.

Three things follow from that.

First, references are lazy. The CDA returns the stored pairs unless you ask it to resolve a path with include[]. Nothing is resolved by default, and a nested reference is only resolved when its full path is included too.

Second, the CDA resolves a reference from what is published. If the referenced entry is not published to the environment and locale you query, there is nothing to inline, and it drops out of the result.

Third, resolution is bounded. Each included level multiplies the entries the CDA has to fetch, so the API caps the number of paths and the depth. Requests that go past those caps fail instead of returning partial data.

If you come from SQL, think of include[] as an explicit join list. There is no lazy loading on access, and the joins you do not name are not made.

Fix it

The path is not included

Include every path the page renders. With the TypeScript Delivery SDK, call includeReference() before you build the query. Nested references use dot notation, and each level needs its own path:

import contentstack, { QueryOperation } from "@contentstack/delivery-sdk";

const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
});

const result = await stack
  .contentType("blogpost")
  .entry()
  .includeReference("author", "author.company", "related_posts")
  .query()
  .where("url", QueryOperation.EQUALS, "/blog/hello-world")
  .find();

author.company resolves the company referenced from the author. Without it, author is resolved and author.company stays a bare UID.

The same request with curl:

curl -G "https://cdn.contentstack.io/v3/content_types/blogpost/entries" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode "include[]=author" \
  --data-urlencode "include[]=author.company" \
  --data-urlencode "include[]=related_posts"

Use your region's CDA host if your stack is not in AWS North America.

If a reference field allows more than one content type, also call includeReferenceContentTypeUID(). Each resolved entry then carries its _content_type_uid, so your renderer knows which component to use.

References inside modular blocks, groups and global fields

Paths follow the schema, not the rendered shape. For a reference inside a block, the path is the modular blocks field UID, then the block UID, then the reference field UID:

const page = await stack
  .contentType("landing_page")
  .entry()
  .includeReference(
    "sections.testimonial.person",
    "sections.card_grid.cards",
    "sections.card_grid.cards.author"
  )
  .query()
  .where("url", QueryOperation.EQUALS, "/pricing")
  .find();

Groups work the same way: group_uid.reference_uid.

Global fields are where most paths go wrong. A global field behaves like a group, and the path uses the UID the global field has on this content type, not the UID of the global field itself. If the seo global field is added to landing_page as page_seo, and it contains a reference og_author, the path is page_seo.og_author. Inside a block, it becomes sections.hero.page_seo.og_author.

Fetch the content type's schema from GET /v3/content_types/landing_page on the CDA and read the uid values from the top down. That is your path. A path that does not match resolves nothing, or fails the request.

The referenced entry is not published

Publishing a blog post does not publish its author. If the author is unpublished, or published to staging but not production, or published in en-us but not de-de, it is missing from the resolved response.

Fix it at the source:

  • Publish the referenced entries to the same environment and locale. In the publish dialog, editors can include references, and nested reference publishing sends them up to five levels deep.

  • For locales, check whether the referenced entry is published in the locale you request. If you rely on fallback, pass include_fallback=true (see Why am I getting en-us content?).

In code, treat a resolved reference as optional. A field that is required in the CMS can still be missing in the delivered JSON:

type Author = { uid: string; title: string; url?: string };

function authorsOf(entry: { author?: Author[] }) {
  return (entry.author ?? []).filter((a): a is Author => Boolean(a?.title));
}

The filter drops stubs that only have a uid, so one missing author does not break the page. The publishing explainer covers releases, bulk publish and nested reference publishing, and Publishing stuck or references not published covers the publish side of this problem.

include_all without a depth

include_all=true resolves every reference field on the entry, but only one level deep. Nested references stay as UIDs. Add include_all_depth to go further:

const page = await stack
  .contentType("landing_page")
  .entry()
  .addParams({ include_all: true, include_all_depth: 2 })
  .query()
  .where("url", QueryOperation.EQUALS, "/pricing")
  .find();

The maximum depth is 5. A higher value returns an error. Use include_all for prototypes and preview tooling. For production pages, list the paths. It is easier to reason about and fetches less.

Too deep or too many includes: 422 with error_code 141

The CDA rejects a request it will not resolve, with 422, error_code: 141 and the message Failed to fetch entries. Please try again with valid parameters. The errors object in the body usually names the parameter. The limits to check:

Limit

Value

Reference paths per request (include[] or include_all)

100

include_all_depth

1 by default, 5 at most

Multiple content type Reference fields

resolve up to 3 levels deep

Request URL size on the CDN

8 KB, above that 414 URI Too Long

Paths count per path, not per entry. sections.card_grid.cards and sections.card_grid.cards.author are two paths. A page with ten block types and three levels each reaches 100 quickly.

When you hit one of these, split the request. Fetch the page with the first levels, collect the UIDs of the deep references, and fetch those in a second query:

const [page] = (await stack
  .contentType("landing_page")
  .entry()
  .includeReference("sections.card_grid.cards")
  .query()
  .where("url", QueryOperation.EQUALS, "/pricing")
  .find()).entries ?? [];

const authorUids = (page?.sections ?? [])
  .flatMap((s: any) => s.card_grid?.cards ?? [])
  .flatMap((card: any) => card.author ?? [])
  .map((ref: { uid: string }) => ref.uid);

const authors = authorUids.length
  ? (await stack
      .contentType("author")
      .entry()
      .query()
      .containedIn("uid", [...new Set(authorUids)])
      .find()).entries ?? []
  : [];

Two small requests are cheaper and easier to cache than one request at the edge of every limit.

Error 141 that has nothing to do with references

141 is a generic code. Before you rewrite include paths, rule out the other causes:

  • The requested object doesn't exist. on a single-entry fetch means that entry is not published in that environment and locale, or the UID belongs to another content type.

  • An environment or locale the delivery token cannot read also returns 422 with 141. Check that the token is scoped to the environment, and that the locale code exists in the stack in lowercase.

  • A malformed query parameter returns the same Failed to fetch entries message.

Strip the request down to environment only. If that works, add parameters back one by one until it fails.

Check that it worked

Run the request with curl and inspect the reference field:

curl -sG "https://cdn.contentstack.io/v3/content_types/landing_page/entries" \
  -H "api_key: $CONTENTSTACK_API_KEY" \
  -H "access_token: $CONTENTSTACK_DELIVERY_TOKEN" \
  --data-urlencode "environment=production" \
  --data-urlencode 'query={"url":"/pricing"}' \
  --data-urlencode "include[]=sections.card_grid.cards" \
  | jq '.entries[0].sections[] | .card_grid.cards[]? | {uid, title}'

Every card should have a title. A card with only uid is either a path you did not include or an entry that is not published. Compare the count with the editor's selection to spot unpublished entries.

Prevent it

  • Keep include paths next to the component that renders them, and build the list for a page from the components it uses. A new block then brings its own paths.

  • Type resolved references as optional in your code. The CMS can require a reference that the delivery response leaves out.

  • Teach editors to publish with references, or bundle pages and their references in a release.

  • Keep reference chains short. A page that references sections, which reference cards, which reference authors, is three levels deep before it renders. Most of those levels can be modular blocks or global fields, which come back with the entry for free. Modular blocks, references or global fields? walks through that decision with examples.

  • Watch the URL length when you build paths programmatically. A long list of includes is the most common source of 414.

Key takeaways

  • References are not resolved unless you include the full dot-notation path, one path per level.

  • Paths follow the schema: blocks field UID, block UID, the global field's UID on this content type, then the reference field UID.

  • A referenced entry that is not published in that environment and locale drops out of the response.

  • include_all stops at depth 1 unless you set include_all_depth, which goes up to 5. A request resolves at most 100 paths.

  • 422 with error_code: 141 is generic. Read the message and the errors object before you change anything.

  • Split deep pages into two queries, and model shared content as blocks or global fields when it does not need its own lifecycle.

Next steps

Frequently asked questions

  • Why does my reference field only contain uid and _content_type_uid?

    References are not resolved unless you ask for them. Add the field path to include[] or call includeReference() with the full dot-notation path.

  • Why is a referenced entry missing from the array even though it exists?

    The referenced entry is not published to that environment and locale. The parent's publish does not publish its references.

  • How deep can include_all go?

    include_all resolves one level by default. include_all_depth raises that up to 5, and a request resolves at most 100 reference paths whatever the depth.

  • What does error_code 141 mean on the Content Delivery API?

    It is a generic 422 code. It covers missing entries, an environment or locale the token cannot read, and request parameters the API rejects, so read the error message and errors object, not just the code.

  • How do I include a reference that sits in a global field inside a modular block?

    Use the full path from the content type, starting with the modular blocks field UID, block UID, the global field's UID on that content type, then the reference field UID.