Diagnosing Pug Template Inheritance Failures: Child Blocks Not Overriding Parent

Recognizable condition

When a child template uses extends layout.pug the rendered output shows the parent’s default block content unchanged, or the compilation fails with one of these messages:

• Cannot extend 'layout.pug'
• Block 'content' already provided
• Unexpected token on the line that starts a block declaration

Cause / diagnostic table

Symptom	Likely cause
Parent block content appears unchanged	Indentation drift (tabs/mixed spaces) or block name mismatch
Compile error “Block … already provided”	Duplicate block declarations in the same file
Compile error “Cannot extend …”	Wrong extends path or missing basedir
Unexpected token on a block line	Using include where extends is required, or mis‑placed extends

Ordered checks

1. Verify the extends path: ensure it is relative to the template’s directory or to the configured basedir option.
2. Compare block names exactly: open parent and child files and confirm the identifiers match in case and spelling.
3. Search the child template for duplicate block names (e.g., two block content lines).
4. Check indentation: the block body must be indented deeper than the block keyword and use only spaces (no tabs).
5. Create a minimal two‑file reproduction (parent layout.pug with a single block, child that extends it and fills the block) to isolate the problem.

Fixes tied to findings

Indentation drift

Replace any tabs with spaces and make sure the block body is indented consistently (commonly 2 or 4 spaces). Re‑run the compile step.

Name mismatch

Rename the child block to exactly match the parent block name, preserving case.

Duplicate blocks

Remove or rename the extra block declaration so each block name appears only once in the template.

Path error

Correct the extends argument (e.g., extends ./layout.pug) or set the basedir option in the Pug compile call to the directory containing the layout.

Wrong construct

If the child only needs to insert a partial, use include; if it must replace the whole document, switch to extends and place it as the first non‑comment statement.

Append/prepend misuse

When the parent defines block append foo or block prepend foo, the child should use a plain block foo (or matching append/prepend) to avoid conflict.

Escalation criteria

If a minimal parent‑child pair still fails after performing the checks above, the issue may be a version‑specific regression or a custom resolver/filter interfering. Capture:

• Exact Pug version (npm ls pug)
• Node version
• The minimal reproduction files
• Any custom filters or loaders in use

Then report the problem to the Pug repository with this information.