Diagnosing Missing Global Data in Eleventy Templates

The Problem

Your Eleventy build completes without errors, but templates render with empty or undefined variables where global data should appear. The generated HTML lacks content that depends on files in the _data directory—no error messages, just missing output.

Quick Diagnostic Table

Symptom	Likely Cause
Variable is undefined in template	Data file not in _data folder, or filename doesn't match variable name
Variable exists but is empty object	Invalid JSON/JS syntax, or async function not returning resolved data
Wrong data appears	Key collision across multiple data files overriding values
Data works locally but not in CI	Eleventy version mismatch (pre-0.11 behavior differs)

Ordered Checks

1. Confirm _data location. The directory must sit at the project root (same level as .eleventy.js or package.json). Run ls -la _data/ from the project root to verify.
2. Match filename to variable. Eleventy maps _data/site.json to the site variable. If your template uses {{ site.title }}, the file must be named site.json (or site.js, site.11tydata.js).
3. Validate file content. For JSON: run cat _data/site.json | jq . to catch syntax errors. For JS modules: ensure the file exports an object or a function returning an object/promise.
4. Check async data resolution. A JS data file exporting async function() { return fetch(...).then(r => r.json()) } works; exporting fetch(...).then(...) without return or await yields empty data silently.
5. Search for key collisions. If _data/site.json and _data/config.json both export a title key, the last-loaded file wins. Run eleventy --debug and inspect the [Eleventy] Global Data log section to see merge order.
6. Verify Eleventy version. Run npx @11ty/eleventy --version. Versions before 0.11 handled global data differently; upgrade with npm install @11ty/eleventy@latest if needed.

Fixes Tied to Findings

Misplaced or misnamed file

Move the file into _data/ and rename to match the template variable. Example: a file at src/data/meta.json used as {{ meta }} in templates must become _data/meta.json.

Syntax error in data file

Correct JSON (trailing commas, unquoted keys) or JS (missing module.exports, syntax errors). A minimal valid JS data file:

// _data/site.11tydata.js
module.exports = {
  title: "My Site",
  url: "https://example.com"
};

Async data not resolving

Ensure the exported function returns the promise or uses await at the top level (requires .11tydata.js extension):

// _data/posts.11tydata.js
module.exports = async function() {
  const res = await fetch('https://api.example.com/posts');
  return res.json();
};

Without return or await, Eleventy receives a pending promise and treats it as empty data.

Key collision

Rename conflicting keys (e.g., siteTitle vs configTitle) or consolidate into a single data file. Use eleventy --debug to confirm load order.

Version upgrade and cache clear

After upgrading Eleventy, clear the cache and rebuild:

rm -rf .eleventy_cache
npx @11ty/eleventy

Run this from the project root with write permissions to the working directory.

Escalation Criteria

If data still doesn't appear after all checks:

1. Disable plugins one by one in .eleventy.js to isolate interference.
2. Inspect .eleventy.js for custom addGlobalData calls or data cascade overrides that may shadow _data files.
3. Check for middleware (e.g., in Eleventy Edge or serverless adapters) that strips data before rendering.
4. Create a minimal reproducible repository: a fresh Eleventy project with one _data/test.json and one template using {{ test }}. If the issue persists, open an issue on Eleventy's GitHub with that reproduction.

Verification Steps

Create a minimal test to confirm the diagnostic flow works:

1. mkdir test-eleventy-data && cd test-eleventy-data
2. npm init -y && npm install @11ty/eleventy
3. mkdir _data _includes
4. Create _data/site.json: {"title": "Test Site"}
5. Create _includes/base.njk: <h1>{{ site.title }}</h1>
6. Create index.njk with front matter: --- layout: base.njk ---
7. Run npx @11ty/eleventy and check _site/index.html contains <h1>Test Site</h1>.
8. Rename _data/site.json to _data/data.json, rebuild, and verify {{ site.title }} renders empty.
9. Restore the name, rebuild, and confirm output returns.

Limitations

• This guide covers global data files only. Template/directory data files (e.g., posts.11tydata.json alongside posts/) follow different scoping rules.
• Custom data extensions via config.addDataExtension() may introduce additional failure modes not covered here.
• Eleventy 3.0 (when released) may change data cascade behavior; verify against the version in use.