Health Check Codes Reference

Bengal's health check system uses prefixed codes for quick identification and filtering. Usebengal validate --ignore <code>to suppress specific checks.

Code Categories

Link Checks (H2xx)

H201: Broken Internal Links

Internal links point to pages that don't exist.

Severity: Error

Common Causes

• Page was moved or deleted
• Typo in link path
• Case sensitivity mismatch

How to Fix

1. Update the link to point to the correct page
2. Create the missing page
3. Remove the broken link

H202: Broken External Links

External links may be temporarily unavailable or incorrect.

Severity: Warning

Common Causes

• External site is down
• URL has changed
• Network connectivity issues

How to Fix

1. Verify the external URL is correct
2. Update to the new URL if it changed
3. Consider using archive links for important references

Output Checks (H3xx)

H301: Suspiciously Small Pages

Pages are unusually small, which may indicate rendering errors.

Severity: Warning

Common Causes

• Template rendering failed silently
• Content is empty
• Fallback HTML was generated

How to Fix

1. Review the page content and template
2. Check for rendering errors in build output
3. Ensure content files have actual content

H302: Missing Assets Directory

No assets directory found in build output.

Severity: Error

Common Causes

• Theme assets not discovered
• Asset copy step failed
• Theme not properly configured

How to Fix

1. Verify theme configuration inbengal.toml
2. Check that theme has assets directory
3. Review build logs for asset copy errors

H303: No CSS Files

No CSS files found in the output.

Severity: Warning

Common Causes

• Theme CSS not copied
• Asset discovery failed
• Theme not applied

How to Fix

1. Check theme configuration
2. Verify CSS files exist in theme
3. Review asset discovery settings

H304: No JS Files

No JavaScript files found in output (for default theme).

Severity: Warning

Common Causes

• JS files not copied
• Asset discovery issue
• Theme doesn't include JS

How to Fix

1. Check if theme requires JavaScript
2. Verify JS files exist in theme assets
3. Review asset discovery configuration

H305: Output Directory Missing

Output directory does not exist after build.

Severity: Error

Common Causes

• Build process failed
• Output path misconfigured
• Permissions issue

How to Fix

1. Check build logs for errors
2. Verifyoutput_dirin configuration
3. Ensure write permissions on target directory

URL Collision Checks (H4xx)

H401: URL Collisions Detected

Multiple pages output to the same URL.

Severity: Error

Common Causes

• Duplicate slugs in frontmatter
• Autodoc section index conflicts
• Manual content at same path as generated content

How to Fix

1. Rename one page or adjust its slug
2. Move autodoc index to a different path
3. Review URL generation in configuration

H402: Section/Page URL Conflict

A page has the same URL as a section.

Severity: Warning

Common Causes

• Page at same path as section_index.md
• Conflicting slug configuration

How to Fix

1. Move the page inside the section
2. Use a different slug for the page
3. Consider making the page the section index

Navigation Checks (H5xx)

H501: Broken Next/Prev Links

Pages have navigation links pointing to missing pages.

Severity: Error

Common Causes

• Bug in navigation system
• Page deleted after navigation computed

How to Fix

1. This is likely a Bengal bug - report it
2. Rebuild the site from scratch
3. Check for orphaned navigation entries

H502: Invalid Breadcrumb Ancestors

Breadcrumb ancestors don't correspond to real sections.

Severity: Error

Common Causes

• Section hierarchy corrupted
• Missing section index files

How to Fix

1. Ensure all sections have_index.md
2. Review section hierarchy
3. Rebuild the site

H503: Invalid Breadcrumb Trails

Breadcrumb trails have issues with section hierarchy.

Severity: Warning

Common Causes

• Section index missing
• Orphaned content pages

How to Fix

1. Add_index.mdto sections
2. Move content into proper sections

H504: Section Navigation Issues

Sections with pages are missing index or archive pages.

Severity: Warning

Common Causes

• Missing_index.mdin section
• Auto-generated archive not created

How to Fix

1. Create_index.mdfor the section
2. Check section configuration

H505: Weight-Based Navigation Issues

Navigation ordering by weight has problems.

Severity: Error

Common Causes

• Bug in navigation system
• Weight values not set correctly

How to Fix

1. Verify weight values in frontmatter
2. This may be a Bengal bug - report it

H506: Missing Output Path

Pages are missing their output path assignment.

Severity: Error

Common Causes

• Critical bug in content discovery
• ContentOrchestrator._set_output_paths()not called

How to Fix

1. This is a Bengal bug - report it
2. Check ContentOrchestrator is running

Menu Checks (H6xx)

H601: Empty Menu

A configured menu has no items.

Severity: Warning

Common Causes

• Menu defined but no items added
• Menu items not matching any pages

How to Fix

1. Add items to the menu in configuration
2. Add menu entries in page frontmatter
3. Remove unused menu definition

H602: Broken Menu Links

Menu items link to pages that may not exist.

Severity: Warning

Common Causes

• Linked page was moved or deleted
• Typo in menu URL

How to Fix

1. Update menu links to correct pages
2. Remove menu items for deleted pages

Directive Checks (H7xx)

H701: Directive Syntax Errors

Directives have syntax errors.

Severity: Error

Common Causes

• Invalid directive name
• Missing closing backticks
• Malformed options

How to Fix

1. Check directive syntax matches MyST format
2. Ensure closing backticks match opening count
3. Review directive documentation

H702: Fence Nesting Issues

Directives use 3 backticks but contain code blocks with 3 backticks.

Severity: Warning

Common Causes

• Code block inside directive uses same fence count
• Nested directives without increasing fence count

How to Fix

1. Change directive opening from ``` to ```` (4+ backticks)
2. Or change inner code blocks to use fewer backticks

Example

❌ Nested with same fence count:

```{note}
Here's some code:
```python
print("hello")
```
```

✅ Correct nesting:

````{note}
Here's some code:
```python
print("hello")
```
````

H703: Incomplete Directives

Directives are incomplete (missing required content or options).

Severity: Error

Common Causes

• Required content missing
• Required options not provided
• Directive body empty when required

How to Fix

1. Add required content to directive body
2. Provide all required options
3. Review directive documentation for requirements

H704: Directive Usage Could Be Improved

Directives could be simplified or improved.

Severity: Warning

Common Causes

• Single-item directives that could be simpler
• Overuse of complex directives

How to Fix

1. Consider simpler alternatives
2. Review if directive is necessary

H705: Heavy Directive Usage

Pages have many directives which may slow rendering.

Severity: Warning

Common Causes

• Complex documentation pages
• Overuse of directives

How to Fix

1. Consider splitting large pages
2. Use simpler formatting where possible

H706: Too Many Tabs

Tab blocks have many tabs which slow rendering.

Severity: Warning

Common Causes

• Many language/platform variations
• Complex comparison content

How to Fix

1. Split into multiple tabs blocks
2. Consider separate pages for some variants

H707: Directive Rendering Errors

Directives failed to render correctly.

Severity: Error

Common Causes

• Missing closing fence
• Invalid directive syntax
• Unknown directive type

How to Fix

1. Check directive syntax
2. Verify closing fence exists
3. Ensure directive is registered

Taxonomy Checks (H8xx)

H801: Missing Tag Pages

Tags have no generated pages.

Severity: Error

Common Causes

• Dynamic page generation failed
• Tag page generation disabled

How to Fix

1. CheckSite.generate_dynamic_pages()is running
2. Verify taxonomy configuration

H802: Orphaned Tag Pages

Tag pages exist but their tags aren't in the taxonomy.

Severity: Error

Common Causes

• Tag was removed from all content
• Taxonomy not properly collected

How to Fix

1. Remove orphaned tag pages
2. Rebuild the site

H803: Missing Tag Index Page

Site has tags but no/tags/index page.

Severity: Warning

Common Causes

• Tag index generation disabled
• Site._create_tag_index_page()not called

How to Fix

1. Enable tag index generation
2. Create manual/tags/_index.md

H804: Sections Without Archive

Sections have content but no archive/index page.

Severity: Warning

Common Causes

• Missing_index.mdin section
• Archive generation disabled

How to Fix

1. Create_index.mdfor the section
2. Enable auto-generated archive pages

H805: Taxonomy Consistency Issues

Taxonomy collection has inconsistencies.

Severity: Error

Common Causes

• Bug inSite.collect_taxonomies()
• Taxonomy data corruption

How to Fix

1. This is likely a Bengal bug - report it
2. Rebuild the site from scratch

H806: Pagination Issues

Pagination generation has problems.

Severity: Error

Common Causes

• Bug in pagination generation
• Invalid pagination configuration

How to Fix

1. Check pagination configuration
2. This may be a Bengal bug - report it

Cache Checks (H9xx)

H901: Legacy Cache Location

Cache is at legacy location (public/.bengal-cache.json).

Severity: Warning

Common Causes

• Site was built with older Bengal version
• Cache not migrated

How to Fix

1. Runbengal buildto migrate cache automatically
2. Or delete old cache and rebuild

H902: Cache Unreadable

Cache file exists but cannot be read.

Severity: Error

Common Causes

• File permissions issue
• Cache file corrupted
• Disk read error

How to Fix

1. Delete cache and rebuild:bengal clean --cache && bengal build
2. Check file permissions

H903: Invalid Cache Structure

Cache structure is invalid or corrupted.

Severity: Error

Common Causes

• Cache corruption
• Interrupted build
• Version mismatch

How to Fix

1. Delete cache and rebuild:bengal clean --cache && bengal build

H904: Very Large Cache File

Cache file is larger than 50 MB.

Severity: Warning

Common Causes

• Many files tracked
• Excessive file tracking
• Cache not cleaned

How to Fix

1. Review what's being cached
2. Clean old cache entries

H905: Too Many Cached Files

Cache is tracking over 10,000 files.

Severity: Warning

Common Causes

• Very large site
• Unnecessary files being tracked

How to Fix

1. Review file tracking configuration
2. Exclude unnecessary files

H906: Orphaned Cache Dependencies

Cache references files that no longer exist.

Severity: Warning

Common Causes

• Files were deleted
• Normal cache staleness

How to Fix

1. Cache will auto-clean on next build
2. Or runbengal clean --cache && bengal build

Performance Checks (H10xx)

H1001: Slow Build Time

Build is slower than expected.

Severity: Warning

Common Causes

• Slow template functions
• Large assets
• System resource constraints

How to Fix

1. Profile build withbengal build --profile
2. Optimize slow template functions
3. Reduce asset sizes

H1002: Slow Throughput

Pages per second is lower than expected.

Severity: Warning

Common Causes

• Parallel builds disabled
• Performance bottlenecks

How to Fix

1. Enable parallel builds:parallel = true
2. Review template complexity
3. Check for blocking operations

H1003: High Average Render Time

Average page render time is high (>100ms/page).

Severity: Warning

Common Causes

• Complex templates
• Slow template functions
• Large page content

How to Fix

1. Simplify templates
2. Optimize template functions
3. Split large pages

Sitemap Checks (H11xx)

H1101: Missing Sitemap

Sitemap.xml was not generated.

Severity: Warning

Common Causes

• Sitemap generation disabled
• SitemapGeneratornot called

How to Fix

1. Enable sitemap generation
2. Check build configuration

H1102: Malformed Sitemap XML

Sitemap XML cannot be parsed.

Severity: Error

Common Causes

• Sitemap generation bug
• File corruption

How to Fix

1. Check sitemap generation logic
2. Rebuild the site

H1103: Invalid Sitemap Root Element

Sitemap root element is noturlset.

Severity: Error

How to Fix

1. This is a Bengal bug - report it
2. Sitemap should have<urlset>as root

H1104: Non-Standard Sitemap xmlns

Sitemap uses non-standard namespace.

Severity: Warning

How to Fix

1. Use standard namespace for compatibility
2. Check sitemap generation template

H1105: Empty Sitemap

Sitemap has no URL elements.

Severity: Warning

Common Causes

• No publishable pages
• Sitemap generation issue

How to Fix

1. Check that site has publishable content
2. Review sitemap generation

H1106: URLs Missing loc Element

Sitemap URLs are missing the required<loc>element.

Severity: Error

How to Fix

1. This is a Bengal bug - report it
2. Each<url>must have a<loc>

H1107: Relative URLs in Sitemap

Sitemap contains relative URLs instead of absolute.

Severity: Error

Common Causes

• baseurlnot configured
• Sitemap generation bug

How to Fix

1. Setbaseurlin configuration
2. Verify sitemap uses absolute URLs

H1108: Duplicate Sitemap URLs

Sitemap contains duplicate URL entries.

Severity: Error

Common Causes

• URL collision in site
• Sitemap generation bug

How to Fix

1. Fix URL collisions (see H401)
2. Report bug if URLs are unique

H1109: Missing Pages in Sitemap

Sitemap has fewer URLs than publishable pages.

Severity: Warning

Common Causes

• Pages excluded from sitemap
• Pages missingoutput_path

How to Fix

1. Review sitemap exclusion settings
2. Check all pages have output paths

RSS Feed Checks (H12xx)

H1201: Missing RSS Feed

RSS feed not generated despite having dated content.

Severity: Warning

Common Causes

• RSS generation disabled
• RSSGeneratornot called

How to Fix

1. Enable RSS generation
2. Check build configuration

H1202: Malformed RSS XML

RSS feed XML cannot be parsed.

Severity: Error

Common Causes

• RSS generation bug
• File corruption

How to Fix

1. Check RSS generation logic
2. Rebuild the site

H1203: Invalid RSS Root Element

RSS root element is notrss.

Severity: Error

How to Fix

1. This is a Bengal bug - report it
2. RSS feed should have<rss>as root

H1204: Non-Standard RSS Version

RSS version is not 2.0.

Severity: Warning

How to Fix

1. Use RSS 2.0 for maximum compatibility
2. Check RSS generation template

H1205: Missing RSS Channel

RSS feed has no<channel>element.

Severity: Error

How to Fix

1. This is a Bengal bug - report it
2. RSS 2.0 requires a<channel>element

H1206: Missing Required Channel Elements

RSS channel missing required elements (title, link, description).

Severity: Error

How to Fix

1. Configure site title and description
2. Setbaseurlin configuration

H1207: Empty RSS Feed

RSS feed has no items.

Severity: Warning

Common Causes

• No dated content
• RSS generation issue

How to Fix

1. Add dated content withdatein frontmatter
2. Review RSS generation logic

H1208: Invalid RSS Items

RSS items missing required elements (title, link).

Severity: Error

How to Fix

1. Ensure content has titles
2. Check RSS item generation

H1209: Relative RSS Channel Link

RSS channel link is relative, not absolute.

Severity: Warning

How to Fix

1. Setbaseurlin configuration
2. Verify RSS uses absolute URLs

H1210: Relative RSS Item URLs

RSS item links are relative instead of absolute.

Severity: Error

How to Fix

1. Setbaseurlin configuration
2. Verify RSS item generation uses absolute URLs

Font Checks (H13xx)

H1301: Missing fonts.css

fonts.css not generated despite font configuration.

Severity: Warning

Common Causes

• FontHelper.process()not called
• Font processing failed

How to Fix

1. Check font configuration
2. Review build logs for font errors

H1302: Missing Fonts Directory

Fonts directory does not exist in output.

Severity: Error

Common Causes

• Font files not downloaded
• Font processing failed

How to Fix

1. Check font configuration
2. Verify network connectivity
3. Review font processing logs

H1303: No Font Files

No font files found in assets/fonts/.

Severity: Error

Common Causes

• Font download failed
• Network connectivity issues

How to Fix

1. Check network connectivity
2. Review font download logs
3. Try manual font installation

H1304: Insufficient Font Files

Fewer font files than expected for configured families.

Severity: Warning

Common Causes

• Some fonts failed to download
• Font family configuration issue

How to Fix

1. Check for download errors in logs
2. Verify font family names

H1305: Cannot Read fonts.css

fonts.css file cannot be read.

Severity: Error

Common Causes

• File permissions issue
• Encoding problem

How to Fix

1. Check file permissions
2. Regenerate fonts.css

H1306: No @font-face Rules

fonts.css has no @font-face declarations.

Severity: Error

Common Causes

• FontCSSGenerator issue
• Empty font configuration

How to Fix

1. Check font configuration
2. Verify FontCSSGenerator is working

H1307: Broken Font References

CSS references font files that don't exist.

Severity: Error

Common Causes

• Font download failed
• Path mismatch

How to Fix

1. Check font files exist
2. Regenerate fonts.css

H1308: Oversized Font Files

Font files are very large (>200 KB).

Severity: Warning

Common Causes

• Using full font families
• Non-subset fonts

How to Fix

1. Use variable fonts
2. Subset fonts to needed characters
3. Use fewer font weights

H1309: Large Total Font Size

Total font size exceeds 1 MB.

Severity: Warning

How to Fix

1. Reduce number of font weights
2. Use font subsetting
3. Consider system fonts

Asset Checks (H14xx)

H1401: Missing Assets Directory

No assets directory found in output.

Severity: Warning

Common Causes

• Assets not copied
• Asset discovery failed

How to Fix

1. Check asset configuration
2. Verify source assets exist

H1402: No CSS Files in Assets

No CSS files found in assets directory.

Severity: Warning

Common Causes

• Theme CSS not discovered
• CSS not copied

How to Fix

1. Check theme has CSS files
2. Review asset discovery settings

H1403: Large CSS Files

CSS files exceed size threshold.

Severity: Warning

How to Fix

1. Enable CSS minification
2. Split large CSS files
3. Remove unused styles

H1404: Large JavaScript Files

JavaScript files exceed size threshold.

Severity: Warning

How to Fix

1. Enable JS minification
2. Use code splitting
3. Remove unused code

H1405: Large Image Files

Image files exceed size threshold.

Severity: Warning

How to Fix

1. Optimize images
2. Use appropriate formats (WebP, AVIF)
3. Resize to needed dimensions

H1406: Large Total Asset Size

Total asset size exceeds 10 MB.

Severity: Warning

How to Fix

1. Optimize all assets
2. Remove unused assets
3. Use CDN for large files

H1407: Unminified CSS

Large CSS files may not be minified.

Severity: Info

How to Fix

1. Enable CSS minification in config
2. Use build-time CSS processing

H1408: Unminified JavaScript

Large JS files may not be minified.

Severity: Info

How to Fix

1. Enable JS minification in config
2. Use build-time JS processing

Connectivity Checks (H15xx)

H1501: Many Isolated Pages

Many pages have no meaningful connections.

Severity: Error

Common Causes

• Missing internal links
• No tags or categories
• Orphaned content

How to Fix

1. Add internal links between related pages
2. Use tags to group related content
3. Add cross-references

H1502: Isolated Pages Found

Some pages are isolated (low connectivity score).

Severity: Warning

How to Fix

1. Add navigation or cross-references
2. Link from related pages

H1503: Lightly-Linked Pages

Pages rely only on structural links.

Severity: Warning

Common Causes

• Only connected via navigation
• No explicit cross-references

How to Fix

1. Add explicit cross-references
2. Link from related content

H1504: Hub Pages Detected

Pages have very many outgoing references.

Severity: Warning

How to Fix

1. Consider splitting into sub-topics
2. Create multiple entry points

H1505: Low Average Connectivity Score

Site-wide connectivity is low.

Severity: Warning

How to Fix

1. Add more internal links
2. Use tags and cross-references
3. Aim for average score >= 1.0

H1506: Low Average Connectivity Links

Average links per page is very low.

Severity: Warning

How to Fix

1. Add more internal links
2. Use cross-reference patterns
3. Well-connected content improves SEO

Config Checks (H16xx)

H1601: Missing Configuration Fields

Recommended configuration fields are missing.

Severity: Warning

How to Fix

1. Add suggested fields tobengal.toml
2. Review configuration documentation

H1602: Trailing Slash in Base URL

Base URL ends with/.

Severity: Info

Common Causes

• Copy/paste error
• Intentional but may cause issues

How to Fix

1. Remove trailing slash frombaseurl
2. baseurl = "https://example.com"not"https://example.com/"

H1603: Very High max_workers

max_workersis set very high (>20).

Severity: Warning

Common Causes

• Over-optimization attempt
• Copy/paste error

How to Fix

1. Reduce to 8-12 workers
2. Very high values may cause resource exhaustion

H1604: Incremental Without Parallel

Incremental builds enabled but parallel disabled.

Severity: Info

How to Fix

1. Enableparallel = truefor faster incremental builds
2. Or this may be intentional for debugging

Rendering Checks (H17xx)

H1701: HTML Structure Issues

Pages have HTML structure problems.

Severity: Warning

Common Causes

• Template missing DOCTYPE
• Missing<html>,<head>, or<body>tags

How to Fix

1. Check template files for proper HTML5 structure
2. Verify base template is complete

H1702: Unrendered Jinja2 Syntax

Pages may have unrendered template syntax.

Severity: Warning

Common Causes

• Template escaping issues
• Documentation examples (which is OK)

How to Fix

1. Check for template rendering errors
2. If documenting Jinja2, escape properly

H1703: Missing Template Functions

Essential template functions not registered.

Severity: Error

Common Causes

• TemplateEngine initialization issue
• Function registration failed

How to Fix

1. This is a Bengal bug - report it
2. Check TemplateEngine.init()

H1704: Template Function Validation Failed

Could not validate template functions.

Severity: Warning

Common Causes

• TemplateEngine initialization problem

How to Fix

1. Check for initialization errors
2. Report if persistent

H1705: Missing SEO Metadata

Pages missing basic SEO elements.

Severity: Warning

Common Causes

• Template missing<title>or meta description
• Frontmatter missing description

How to Fix

1. Add<title>to templates
2. Add meta description tags
3. Setdescriptionin frontmatter

Track Checks (H18xx)

H1801: Invalid Track Structure

Track configuration is not a dictionary.

Severity: Error

How to Fix

1. Fix track definition intracks.yaml
2. Use dict withtitleanditemsfields

H1802: Track Missing items Field

Track missing requireditemsfield.

Severity: Error

How to Fix

1. Additemslist to track definition
2. Include page paths in items

H1803: Track items Not a List

Trackitemsfield is not a list.

Severity: Error

How to Fix

1. Use list syntax for items:items: [page1.md, page2.md]

H1804: Invalid Track Item Type

Track item is not a string.

Severity: Warning

How to Fix

1. Use string page paths for track items
2. Example:items: ["guide/intro.md", "guide/basics.md"]

H1805: Missing Track Pages

Track references pages that don't exist.

Severity: Warning

How to Fix

1. Check page paths intracks.yaml
2. Create missing pages or remove references

H1806: Invalid track_id in Page

Page references a track that doesn't exist.

Severity: Warning

How to Fix

1. Add the track totracks.yaml
2. Or removetrack_idfrom page frontmatter

Anchor Checks (H19xx)

H1901: Duplicate Anchor IDs

Page has duplicate anchor IDs.

Severity: Error (strict) / Warning (default)

Common Causes

• Duplicate headings
• Conflicting explicit anchor IDs

How to Fix

1. Rename one of the duplicates
2. Use unique anchor IDs

H1902: Broken Anchor References

Anchor references point to non-existent anchors.

Severity: Warning

Common Causes

• Typo in anchor reference
• Target heading was renamed/deleted

How to Fix

1. Fix the anchor reference
2. Add explicit anchor with{#id}syntax
3. Check similar anchors suggested in error

Ownership Checks (H20xx)

H2001: Reserved Namespace Violations

User content placed in reserved namespaces.

Severity: Warning

Reserved Namespaces

• /tags/- reserved for taxonomy
• /search/,/404.html,/graph/- reserved for special pages
• Autodoc prefixes - reserved for autodoc output

How to Fix

1. Move content to a different path
2. Adjust the slug in frontmatter
3. Use a custom section instead

Using --ignore

To suppress specific health checks, use the--ignoreflag:

# Ignore a single code
bengal validate --ignore H202

# Ignore multiple codes
bengal validate --ignore H202 --ignore H1403 --ignore H1404

# Combine with other options
bengal validate --verbose --ignore H301

Common ignore patterns:

# Ignore external link checks (for offline development)
bengal validate --ignore H202

# Ignore performance warnings during development
bengal validate --ignore H1001 --ignore H1002 --ignore H1003

# Ignore asset size warnings for documentation sites
bengal validate --ignore H1403 --ignore H1404 --ignore H1405

Getting Help

If you encounter a health check issue:

1. Check this page for the code (Ctrl+F / Cmd+F)
2. Review the suggested fix
3. Run with--verbosefor more details
4. Check the troubleshooting guide

For bugs or unclear errors, please open an issue.