Debugging Eleventy Layout Errors: When AI Becomes Your Best Rubber Duck

A technical deep-dive into solving layout path issues and missing frontmatter in Eleventy, featuring AI-assisted debugging that actually worked.

Sometimes you build something amazing, fire up the dev server, and immediately discover that perfection is a myth. Yesterday's triumph was today's "You're trying to use a layout that does not exist: _includes/layout.njk" error message, staring at me from the terminal like a smug reminder that nothing ever works on the first try.

But here's what made this debugging session different: I had an AI pair programmer who could read through file structures, analyze error traces, and propose solutions faster than I could even formulate the problem.

The Problem: Multiple Failure Modes

What started as excitement about a working site quickly turned into three distinct issues:

  1. Layout Resolution Errors: Eleventy couldn't find _includes/layout.njk
  2. Missing Titles: Posts page showed empty link tags like <a href="/posts/resume-cv/"></a>
  3. Broken Content Pipeline: Several files had malformed or missing frontmatter

The error trace was beautifully unhelpful:

[11ty] You're trying to use a layout that does not exist: _includes/layout.njk (via `layout: layout.njk`)

AI-Assisted Debugging: Better Than Rubber Duck

Traditional rubber duck debugging involves explaining your problem to an inanimate object until you figure out the solution yourself. AI debugging is like having a rubber duck that talks back with useful suggestions.

The AI immediately started systematic investigation:

  1. File Structure Analysis: Checked the _includes directory structure
  2. Template Inspection: Examined how layout references were defined
  3. Error Pattern Recognition: Identified that multiple files were missing proper frontmatter
  4. Dependency Mapping: Traced which templates were breaking the build

The Layout Issue

The AI caught something I'd missed: inconsistent layout naming. Some templates referenced layout.njk while others used layouts/base.njk. The actual file was _includes/layouts/base.njk.

Quick fix:

# Wrong
layout: layout.njk

# Right  
layout: layouts/base.njk

The Missing Titles Problem

More interesting was the empty title links issue. The AI systematically checked the generated HTML and found the smoking gun:

<a href="/posts/resume-cv/"></a>
<a href="/posts/resume-index/"></a>
<a href="/posts/now-index/"></a>

These pointed to files with missing or malformed frontmatter. Several markdown files had no YAML frontmatter block at all—they started directly with # Heading content.

The Frontmatter Fix

The AI proposed adding proper frontmatter to each broken file:

---
title: "Resume – Matthew Hendricks"
date: 2025-05-29
tags: [resume]
summary: "Technical writer, developer, and creative systems thinker."
slug: resume-cv
---

But here's what impressed me: it suggested contextually appropriate titles, tags, and summaries based on the content of each file. Not generic placeholders, but thoughtful metadata that matched the writing style and content strategy.

Why AI Debugging Actually Worked

Speed: The AI could scan file structures and analyze error patterns faster than I could mentally map the relationships.

Pattern Recognition: It immediately spotted that multiple files shared the same issue (missing frontmatter) rather than treating each as an isolated problem.

Systematic Approach: Instead of random poking around, it methodically checked each component: templates, layouts, data flow, output generation.

Context Retention: It remembered the entire project structure and could reference earlier conversations about the intended setup.

The Meta-Debugging Moment

The really wild part was when the AI suggested we should write about this debugging session. Which we're now doing. Using the system we just fixed. Which will analyze this post's content and suggest related articles about debugging and AI tools.

Lessons for Technical Collaboration

Document Your Errors: Error logs become more valuable when you have an AI that can analyze patterns across multiple failure modes.

Systematic > Random: AI excels at systematic investigation. Let it suggest the debugging sequence rather than jumping around randomly.

File Structure Matters: Clear, consistent naming conventions make AI assistance more effective. The AI could spot inconsistencies precisely because most of the codebase followed clear patterns.

Frontmatter Validation: Consider adding automated checks for required frontmatter fields before your build process.

The Fixed System

After the debugging session:

  • âś… All layouts resolve correctly
  • âś… Every post has proper titles and metadata
  • âś… Semantic embeddings generation works smoothly
  • âś… Related content suggestions are accurate
  • âś… Tag pages generate automatically

Beyond Rubber Duck

AI-assisted debugging isn't replacing traditional problem-solving skills—it's amplifying them. The AI couldn't have fixed these issues without understanding the intended system architecture and content strategy. But once it understood the goals, it could investigate and propose solutions faster and more systematically than traditional debugging approaches.

The result? A publishing system that works, a debugging workflow that's oddly enjoyable, and a blog post about debugging written with the help of the AI that helped debug the system that's publishing the blog post.

Meta-recursion achievement unlocked.

Technical Details

For anyone facing similar Eleventy issues:

Layout Resolution: Eleventy looks for layouts in the _includes directory by default. Reference them relative to that directory: layouts/base.njk, not _includes/layouts/base.njk.

Frontmatter Validation: Consider a pre-build script that checks for required fields:

// Check for title, date, and tags in all markdown files
const matter = require('gray-matter');
const glob = require('glob');

glob('content/**/*.md', (err, files) => {
  files.forEach(file => {
    const { data } = matter.read(file);
    if (!data.title || !data.date || !data.tags) {
      console.warn(`Missing frontmatter in ${file}`);
    }
  });
});

Error Debugging: Enable Eleventy's debug mode to get more detailed error information:

DEBUG=Eleventy* npx @11ty/eleventy --serve

The system is running smoothly now, ready to help generate the next round of content about our AI-assisted creative process.

This post was debugged and written with AI assistance, naturally.