Diagnosing and Fixing Common Pug Compilation and Rendering Errors

Why Pug Errors are Hard to Spot

Pug (formerly Jade) compiles templates at runtime. A single whitespace mistake or a missing variable can cause the entire rendering pass to fail. Because the error messages are often terse—"Unexpected token" or "ReferenceError"—you need a structured approach to narrow down the culprit.

Recognizable Error Conditions

Below are the five most common failure modes, each paired with a typical cause and a quick diagnostic hint.

Condition	Common Cause	Diagnostic Hint
Unexpected token	Mixed tabs and spaces	Look for a line that starts with a different width of whitespace than the previous line.
ReferenceError: <var> is not defined	Variable not passed in locals	Check the locals object in the render call.
MixinNotFoundError	Calling a mixin before it’s defined or out of scope	Verify mixin declaration order.
Attribute syntax error	Incorrect parentheses or brackets in attribute lists	Inspect the attribute line for stray characters.
Memory exhaustion / hanging process	Rendering a very large template without streaming	Observe Node’s memory usage or a timeout.

Ordered Diagnostic Checklist

1. Run the Pug CLI compiler

   Isolate syntax errors from application logic by compiling the file directly. Run this in your terminal with the appropriate project permissions:

   npx pug path/to/template.pug --pretty -o ./dist

   Expected result: a clean .html file with no compiler errors.

2. Validate indentation

   Pug uses whitespace to denote nesting. Open the file in an editor that highlights tabs versus spaces, or run a linter such as pug-lint:

   npx pug-lint path/to/template.pug

   Fix any mixed‐indentation lines and re‐run the compiler.

3. Check the locals object

   When rendering in Node, verify that all referenced variables are supplied in the locals object passed to the render function:

   const locals = { user: { name: 'Alice' } };
   pug.renderFile('profile.pug', locals, (err, html) => { /* ... */ });

   Use console.log(locals) or a debugger to confirm the payload before the render call.

4. Confirm mixin order and scope

   Mixins must be defined before first use unless you use the include directive. If a mixin accesses a variable, that variable must be in scope where the mixin is called.

   // Correct order
   mixin button(label)
     button= label
   
   +button('Click me')
   

5. Validate attribute syntax

   Attributes are specified with parentheses. Misplaced brackets or missing commas cause parsing failures.

   a(href=link, class='btn') Link
   

   Check that each attribute line ends with a comma or is the last attribute before the closing parenthesis.

6. Use streaming for large templates

   When a template exceeds a few megabytes, compile it with the streaming API to avoid high memory usage and potential process hangs.

   const { createReadStream, createWriteStream } = require('fs');
   const pug = require('pug');
   const input = createReadStream('huge.pug');
   const output = createWriteStream('huge.html');
   const stream = pug.compileFileClient('huge.pug', { pretty: true, client: false });
   input.pipe(stream).pipe(output);
   

Concrete Example: Indentation‐Related Failure

Consider a template menu.pug with mixed whitespace:

ul
  li Home
	li About
	  li Team

The second li line uses a tab while the rest use spaces. Running the CLI yields:

Unexpected token in line 3, column 1: 'li About'

Fix: Replace the tab with two spaces (matching the indentation level).

ul
  li Home
  li About
    li Team

Re‐compile and the output matches the intended hierarchy.

Risk & Limitation Notes

• Escaping: Dynamic attributes that include user input must be escaped to prevent XSS. Use pug.escape or double braces {{}} for interpolation.
• Performance: Complex mixins that perform heavy logic can increase compilation time. Profile with node --inspect-brk if the template renders slowly.
• Environment: This guide assumes Node.js >= 18 and Pug >= 3.0. Verify the installed version with npm list pug.
• Testing: Always run the Pug CLI on a copy of the template before deploying. Automated tests that render the template with a mock locals object help catch runtime errors early.

Escalation Criteria

If after following the checklist the error persists, consider:

• Inspecting the full stack trace to locate the failing line in the generated JavaScript.
• Creating a minimal reproducible example and submitting it to the Pug issue tracker.
• Reviewing recent changes to the template or the locals passed from the controller.