Debugging the Eleventy Data Cascade: Resolving Unexpected Template Values

The Problem: Missing or Overridden Template Data

When a variable in an Eleventy template returns undefined or displays an outdated value despite being defined in a data file, the issue is usually a conflict within the Data Cascade. The cascade is the hierarchical process Eleventy uses to merge data from multiple sources into a single object available to your template.

The primary takeaway: The most specific data source always wins. If a key exists in both a global JSON file and the template's front matter, the front matter value will be used, regardless of what is defined elsewhere.

Diagnostic: Identifying the Data Source Conflict

Use this table to identify where your data is likely being dropped or overridden based on the symptom you are seeing.

Symptom	Likely Cause	Cascade Level
Value is undefined across all pages	Incorrect filename or syntax error in _data	Global Data
Value is correct on some pages, wrong on others in the same folder	Front matter is overriding directory data	Template Data
Value is wrong for an entire section of the site	Parent directory data file is overriding global data	Directory Data
JavaScript data file returns no values	Missing module.exports or async function error	Logic Error

Step-by-Step Data Validation

Follow these checks in order to isolate where the cascade is failing. These steps assume you are using Eleventy v2.0 or later.

1. Verify Global Data Availability

Check if the data is loading at the highest level. If you have a file at _data/site.json, Eleventy makes this available as site in your templates.

• Check: Ensure the filename is lowercase and contains no typos.
• Check: Validate JSON syntax. A missing comma or trailing comma in a .json file can cause Eleventy to ignore the file or fail the build.

2. Trace Directory Data Inheritance

Directory data files (e.g., posts.json.11tydata.js) apply to every template in that folder and its subfolders. If you have nested directories, the file closest to the template takes precedence.

• Check: Look for .11tydata.js or .11tydata.json files in the current folder and every parent folder up to the root.
• Check: Ensure the filename matches the required pattern. A file named data.json inside a folder is treated as a content file, not a data file, unless it has the .11tydata suffix.

3. Inspect Template-Specific Data

Template data files share the same basename as the template. For example, about.md will look for about.11tydata.js.

• Check: Verify that the basename matches exactly. Case sensitivity matters on Linux/macOS environments.

4. Audit Front Matter

Front matter is the final step in the cascade and has the highest priority.

• Check: Search the template's YAML front matter for the specific key. If the key exists here, it will override everything from _data and directory files.

Concrete Example: The Override Chain

Consider a scenario where you want to set a page title. Here is how the merge behaves:

# 1. Global Data (_data/site.json)
{ "title": "My Awesome Site" }

# 2. Directory Data (blog/blog.11tydata.json)
{ "title": "The Blog Section" }

# 3. Template Front Matter (blog/post-1.md)
---
title: "My First Post"
---

Result: The rendered page will display "My First Post". If you remove the front matter, it will display "The Blog Section". If you remove the directory data, it will fall back to "My Awesome Site".

Fixing Common Implementation Errors

Fixing JavaScript Data Exports

If you are using .js data files, you must export the data. A common mistake is defining a variable but not exporting it.

Incorrect:

const data = { layout: 'base.njk' }; // This will be ignored

Correct:

module.exports = {
  layout: 'base.njk',
  date: new Date().getFullYear()
};

Diagnostic Command

To verify your current version and ensure you aren't encountering a version-specific bug, run this in your terminal:

npx @11ty/eleventy --version

Verification and Rollback

How to verify the fix: Create a temporary debug page with the following code in your template (assuming Nunjucks):

<pre>{{ site | dump(2) }}</pre>

This will print the entire global data object to the browser, allowing you to see exactly what Eleventy has loaded.

Rollback: Because data cascade changes typically involve renaming files or editing JSON/YAML, rollback consists of reverting the specific file change via Git: git checkout path/to/data-file.json.

Escalation Criteria

If the following conditions are met and the data is still missing, the issue is likely not the cascade but a plugin or filter conflict:

• The file is named correctly with .11tydata.
• The JSON is valid.
• There is no overlapping key in the front matter.
• The --version check confirms you are on a stable release.