Diagnosing Eleventy Data Cascade Issues: Missing or Overridden Values

Recognizable Condition

Pages render with missing or incorrect data values that were defined in global or template front matter but do not appear in the output.

Cause / Diagnostic Table

Symptom	Likely Cause
Expected global data missing from rendered page	Page front matter defines a key with the same name, overriding global data (lower‑priority source wins)
Array values from global data are replaced instead of concatenated	Eleventy’s default shallow merge replaces the whole array when a lower‑priority source defines the same key
Data appears as `Promise { }` or is undefined	An async data function returns a promise that is not awaited before rendering

Ordered Checks

1. Log the merged data context for a template. Add {{ data | json }} to the template (or a layout) and run npx @11ty/eleventy --serve. Inspect the output for the suspect key.
2. Confirm the data source hierarchy: global → directory → template → front matter. You can temporarily log eleventyConfig.getData() in your eleventy.config.js to see what each layer contributes.
3. If the key is an array or object, check whether a lower‑priority source (e.g., the page’s front matter) redefines it. Look for the same key in _data files, directory data, and the page’s front matter.
4. For async data functions, review the build log for any lines showing Promise { <pending> }. Ensure the function returns a resolved value or is properly awaited.

Fixes Tied to Findings

Override by front matter

If a page unintentionally overrides a global key, rename the page’s front‑matter key (e.g., change navItems to pageNav) or move the global value to a dedicated data file (_data/nav.js) and keep the page front matter free of that key.

Shallow merge replacing arrays

Enable deep merge for the entire site (Eleventy v1.0.0+):

// eleventy.config.js
module.exports = function(eleventyConfig) {
  eleventyConfig.setDataDeepMerge(true);
  return {};
};

If you cannot upgrade, manually concatenate arrays in a custom data file:

// _data/nav.js
module.exports = function({collections, globalData}) {
  const base = globalData.navItems || [];
  const extra = this.page.frontMatter.navItemsAppend || [];
  return [...base, ...extra];
};

Unresolved async data

Make sure the async data function returns a resolved value:

// _data/siteMeta.js
module.exports = async function() {
  const resp = await fetch('https://example.com/config.json');
  return resp.json();
};

Or, if you prefer a synchronous wrapper, return the value directly after awaiting inside the function.

Escalation Criteria

• After verifying the cascade order, confirming merge settings, and ensuring async data resolves, the data still appears incorrect in the rendered HTML.
• You have produced a minimal reproducible example that includes eleventy.config.js, relevant _data files, directory data, and a sample template showing the problem.
• Open an issue in the Eleventy repository () with that example, the Eleventy version you are using, and the build log.