# Health Check Codes Reference

URL: /docs/reference/errors/health-codes/
Section: errors
Tags: reference, health, validation

--------------------------------------------------------------------------------

Health Check Codes Reference Bengal's health check system uses prefixed codes for quick identification and filtering. Use bengal validate --ignore <code> to suppress specific checks. Code Categories Prefix Category Description H2xx Links Internal and external link validation H3xx Output Build output directory and asset checks H4xx URL Collisions Duplicate URL detection H5xx Navigation Next/prev links, breadcrumbs, section navigation H6xx Menus Menu configuration and links H7xx Directives MyST directive syntax and usage H8xx Taxonomy Tags, categories, and pagination H9xx Cache Build cache integrity H10xx Performance Build timing and throughput H11xx Sitemap Sitemap.xml validation H12xx RSS RSS feed validation H13xx Fonts Font configuration and files H14xx Assets CSS, JS, and image files H15xx Connectivity Knowledge graph and page linking H16xx Config Configuration file validation H17xx Rendering Template and HTML output validation H18xx Tracks Learning track configuration H19xx Anchors Heading anchors and references H20xx Ownership Reserved namespace violations 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 Update the link to point to the correct page Create the missing page 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 Verify the external URL is correct Update to the new URL if it changed 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 Review the page content and template Check for rendering errors in build output 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 Verify theme configuration in bengal.toml Check that theme has assets directory 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 Check theme configuration Verify CSS files exist in theme 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 Check if theme requires JavaScript Verify JS files exist in theme assets 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 Check build logs for errors Verify output_dir in configuration 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 Rename one page or adjust its slug Move autodoc index to a different path 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 Move the page inside the section Use a different slug for the page 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 This is likely a Bengal bug - report it Rebuild the site from scratch 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 Ensure all sections have _index.md Review section hierarchy 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 Add _index.md to sections Move content into proper sections H504: Section Navigation Issues Sections with pages are missing index or archive pages. Severity: Warning Common Causes Missing _index.md in section Auto-generated archive not created How to Fix Create _index.md for the section 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 Verify weight values in frontmatter 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 This is a Bengal bug - report it 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 Add items to the menu in configuration Add menu entries in page frontmatter 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 Update menu links to correct pages 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 Check directive syntax matches MyST format Ensure closing backticks match opening count 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 Change directive opening from ``` to ```` (4+ backticks) 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 Add required content to directive body Provide all required options 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 Consider simpler alternatives 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 Consider splitting large pages 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 Split into multiple tabs blocks 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 Check directive syntax Verify closing fence exists 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 Check Site.generate_dynamic_pages() is running 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 Remove orphaned tag pages 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 Enable tag index generation Create manual /tags/_index.md H804: Sections Without Archive Sections have content but no archive/index page. Severity: Warning Common Causes Missing _index.md in section Archive generation disabled How to Fix Create _index.md for the section Enable auto-generated archive pages H805: Taxonomy Consistency Issues Taxonomy collection has inconsistencies. Severity: Error Common Causes Bug in Site.collect_taxonomies() Taxonomy data corruption How to Fix This is likely a Bengal bug - report it 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 Check pagination configuration 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 Run bengal build to migrate cache automatically 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 Delete cache and rebuild: bengal clean --cache && bengal build 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 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 Review what's being cached 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 Review file tracking configuration 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 Cache will auto-clean on next build Or run bengal 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 Profile build with bengal build --profile Optimize slow template functions 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 Enable parallel builds: parallel = true Review template complexity 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 Simplify templates Optimize template functions Split large pages Sitemap Checks (H11xx) H1101: Missing Sitemap Sitemap.xml was not generated. Severity: Warning Common Causes Sitemap generation disabled SitemapGenerator not called How to Fix Enable sitemap generation Check build configuration H1102: Malformed Sitemap XML Sitemap XML cannot be parsed. Severity: Error Common Causes Sitemap generation bug File corruption How to Fix Check sitemap generation logic Rebuild the site H1103: Invalid Sitemap Root Element Sitemap root element is not urlset. Severity: Error How to Fix This is a Bengal bug - report it Sitemap should have <urlset> as root H1104: Non-Standard Sitemap xmlns Sitemap uses non-standard namespace. Severity: Warning How to Fix Use standard namespace for compatibility 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 Check that site has publishable content Review sitemap generation H1106: URLs Missing loc Element Sitemap URLs are missing the required <loc> element. Severity: Error How to Fix This is a Bengal bug - report it Each <url> must have a <loc> H1107: Relative URLs in Sitemap Sitemap contains relative URLs instead of absolute. Severity: Error Common Causes baseurl not configured Sitemap generation bug How to Fix Set baseurl in configuration 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 Fix URL collisions (see H401) 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 missing output_path How to Fix Review sitemap exclusion settings 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 RSSGenerator not called How to Fix Enable RSS generation 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 Check RSS generation logic Rebuild the site H1203: Invalid RSS Root Element RSS root element is not rss. Severity: Error How to Fix This is a Bengal bug - report it RSS feed should have <rss> as root H1204: Non-Standard RSS Version RSS version is not 2.0. Severity: Warning How to Fix Use RSS 2.0 for maximum compatibility Check RSS generation template H1205: Missing RSS Channel RSS feed has no <channel> element. Severity: Error How to Fix This is a Bengal bug - report it 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 Configure site title and description Set baseurl in configuration H1207: Empty RSS Feed RSS feed has no items. Severity: Warning Common Causes No dated content RSS generation issue How to Fix Add dated content with date in frontmatter Review RSS generation logic H1208: Invalid RSS Items RSS items missing required elements (title, link). Severity: Error How to Fix Ensure content has titles Check RSS item generation H1209: Relative RSS Channel Link RSS channel link is relative, not absolute. Severity: Warning How to Fix Set baseurl in configuration Verify RSS uses absolute URLs H1210: Relative RSS Item URLs RSS item links are relative instead of absolute. Severity: Error How to Fix Set baseurl in configuration 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 Check font configuration 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 Check font configuration Verify network connectivity 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 Check network connectivity Review font download logs 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 Check for download errors in logs 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 Check file permissions 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 Check font configuration 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 Check font files exist 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 Use variable fonts Subset fonts to needed characters Use fewer font weights H1309: Large Total Font Size Total font size exceeds 1 MB. Severity: Warning How to Fix Reduce number of font weights Use font subsetting 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 Check asset configuration 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 Check theme has CSS files Review asset discovery settings H1403: Large CSS Files CSS files exceed size threshold. Severity: Warning How to Fix Enable CSS minification Split large CSS files Remove unused styles H1404: Large JavaScript Files JavaScript files exceed size threshold. Severity: Warning How to Fix Enable JS minification Use code splitting Remove unused code H1405: Large Image Files Image files exceed size threshold. Severity: Warning How to Fix Optimize images Use appropriate formats (WebP, AVIF) Resize to needed dimensions H1406: Large Total Asset Size Total asset size exceeds 10 MB. Severity: Warning How to Fix Optimize all assets Remove unused assets Use CDN for large files H1407: Unminified CSS Large CSS files may not be minified. Severity: Info How to Fix Enable CSS minification in config Use build-time CSS processing H1408: Unminified JavaScript Large JS files may not be minified. Severity: Info How to Fix Enable JS minification in config 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 Add internal links between related pages Use tags to group related content Add cross-references H1502: Isolated Pages Found Some pages are isolated (low connectivity score). Severity: Warning How to Fix Add navigation or cross-references 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 Add explicit cross-references Link from related content H1504: Hub Pages Detected Pages have very many outgoing references. Severity: Warning How to Fix Consider splitting into sub-topics Create multiple entry points H1505: Low Average Connectivity Score Site-wide connectivity is low. Severity: Warning How to Fix Add more internal links Use tags and cross-references Aim for average score >= 1.0 H1506: Low Average Connectivity Links Average links per page is very low. Severity: Warning How to Fix Add more internal links Use cross-reference patterns Well-connected content improves SEO Config Checks (H16xx) H1601: Missing Configuration Fields Recommended configuration fields are missing. Severity: Warning How to Fix Add suggested fields to bengal.toml 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 Remove trailing slash from baseurl baseurl = "https://example.com" not "https://example.com/" H1603: Very High max_workers max_workers is set very high (>20). Severity: Warning Common Causes Over-optimization attempt Copy/paste error How to Fix Reduce to 8-12 workers Very high values may cause resource exhaustion H1604: Incremental Without Parallel Incremental builds enabled but parallel disabled. Severity: Info How to Fix Enable parallel = true for faster incremental builds 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 Check template files for proper HTML5 structure 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 Check for template rendering errors 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 This is a Bengal bug - report it Check TemplateEngine.init() H1704: Template Function Validation Failed Could not validate template functions. Severity: Warning Common Causes TemplateEngine initialization problem How to Fix Check for initialization errors 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 Add <title> to templates Add meta description tags Set description in frontmatter Track Checks (H18xx) H1801: Invalid Track Structure Track configuration is not a dictionary. Severity: Error How to Fix Fix track definition in tracks.yaml Use dict with title and items fields H1802: Track Missing items Field Track missing required items field. Severity: Error How to Fix Add items list to track definition Include page paths in items H1803: Track items Not a List Track items field is not a list. Severity: Error How to Fix 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 Use string page paths for track items Example: items: ["guide/intro.md", "guide/basics.md"] H1805: Missing Track Pages Track references pages that don't exist. Severity: Warning How to Fix Check page paths in tracks.yaml 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 Add the track to tracks.yaml Or remove track_id from 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 Rename one of the duplicates 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 Fix the anchor reference Add explicit anchor with {#id} syntax 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 Move content to a different path Adjust the slug in frontmatter Use a custom section instead Using --ignore To suppress specific health checks, use the --ignore flag: # 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: Check this page for the code (Ctrl+F / Cmd+F) Review the suggested fix Run with --verbose for more details Check the troubleshooting guide For bugs or unclear errors, please open an issue.

--------------------------------------------------------------------------------

Metadata:
- Author: lbliii
- Word Count: 3714
- Reading Time: 19 minutes