bengal-debug-build

name	bengal-debug-build
description	Debugs Bengal build failures and errors. Use when builds fail, validation errors occur, or when fixing build errors.

Bengal Debug Build

Debug Bengal build failures and validation errors.

Procedure

Step 1: Run Build and Capture Output

bengal build

Capture the full error output. Common failure points:

• Template rendering (undefined variables, syntax)
• Directive parsing (invalid syntax, missing required args)
• Config loading (invalid bengal.toml)
• Content parsing (invalid frontmatter, malformed markdown)

Step 2: Run Validation

bengal validate

Validation runs health checks including:

• Template context validation (missing variables)
• Directive syntax
• Config schema
• Content structure

Use --verbose for full output, --templates to focus on template errors.

Step 3: Template Context Errors

If the error mentions "Missing context variables" or a template name:

• Check the template references variables that exist in the context
• Use params.x not page.metadata.get('x')
• Use config.x not site.config.get('x')
• Add the variable to the template context or use safe patterns (see bengal-template-fix skill)

Step 4: Directive Errors

If the error mentions a directive (e.g., :::{note}):

• Check directive syntax: :::{name} optional_title
• Options use :key: value format
• Ensure closing :::
• For custom directives, verify registration in directive registry

Step 5: Cache Issues

If builds behave inconsistently or show stale content:

bengal build --full

Forces a full rebuild, ignoring incremental cache.

Step 6: Config Errors

• Validate bengal.toml syntax (TOML format)
• Check [build], [theme] sections
• Ensure content_dir and output_dir exist or can be created

Checklist

• Run bengal build and capture full error
• Run bengal validate for health checks
• Check template context (undefined vars)
• Check directive syntax in content
• Try bengal build --full if cache suspected
• Verify bengal.toml is valid TOML

Additional Resources

See references/error-codes.md for common errors and fixes.