# Error Code Reference

URL: /docs/reference/errors/
Section: errors
Tags: reference, errors, troubleshooting

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

Error Code Reference Bengal uses prefixed error codes for quick identification and searchability. Each code links to its entry below with explanations and solutions. Code Systems Bengal has two code systems: Build Errors (Axxx-Xxxx): Errors that occur during the build process. These stop the build or cause content issues. Health Codes (Hxxx): Health check warnings and suggestions from bengal validate. See Health Check Codes for the complete reference. Build Error Categories Prefix Category Description A Cache Build cache operations errors C Config Configuration loading and validation errors D Discovery Content and section discovery errors G Graph Graph analysis errors N Content Content file parsing and frontmatter errors P Parsing YAML, JSON, TOML, and markdown parsing errors R Rendering Template rendering and output generation errors S Server Development server errors T Template Function Shortcode, directive, and icon errors X Asset Static asset processing errors Cache Errors (Axxx) A001: Cache Corruption The build cache has become corrupted and cannot be read. Common Causes Interrupted build process Disk space issues during cache write Manual modification of cache files How to Fix Delete the .bengal/cache/ directory Run bengal build to regenerate the cache A002: Cache Version Mismatch The cache was created with a different Bengal version. Common Causes Bengal was upgraded or downgraded Cache from a different project How to Fix Delete the .bengal/cache/ directory Run bengal build to regenerate with current version A003: Cache Read Error Failed to read from the build cache. Common Causes File permissions issue Cache file was deleted mid-build Disk read error How to Fix Check file permissions on .bengal/cache/ Delete and regenerate the cache if corrupted A004: Cache Write Error Failed to write to the build cache. Common Causes Insufficient disk space File permissions issue Directory doesn't exist How to Fix Check available disk space Verify write permissions on .bengal/ directory A005: Cache Invalidation Error Failed to invalidate stale cache entries. Common Causes Cache corruption Concurrent build processes How to Fix Delete .bengal/cache/ and rebuild Avoid running multiple builds simultaneously A006: Cache Lock Timeout Could not acquire cache lock within timeout period. Common Causes Another Bengal process is running Previous build crashed while holding lock How to Fix Wait for other builds to complete Delete .bengal/cache/*.lock files if no builds are running Config Errors (Cxxx) C001: Config YAML Parse Error Invalid YAML/TOML syntax in configuration file. The configuration file (bengal.toml or bengal.yaml) contains invalid syntax that cannot be parsed. Bengal cannot start without a valid configuration file. Common Causes Missing colons after keys Incorrect indentation (YAML uses spaces, not tabs) Unquoted special characters (:, #, @) Unclosed quotes or brackets Mixing YAML and TOML syntax How to Fix Check the line number in the error message Look for the common issues listed above Use a YAML validator: https://yamlvalidator.com Compare with the example config in Bengal documentation Example ❌ Invalid: title My Site # Missing colon ✅ Valid: title: My Site C002: Config Key Missing A required configuration key was not found. The configuration file is missing a required key. Some Bengal features require specific configuration to be present. Common Causes Typo in configuration key name Key defined in wrong section Missing required configuration section How to Fix Check the spelling of the configuration key Verify the key is in the correct section Review the Bengal configuration reference C003: Config Invalid Value A configuration value failed validation. A configuration value is not valid for its setting. This could be a wrong type, an invalid option, or a value outside allowed range. Common Causes Using an unsupported value for a setting Type mismatch (e.g., string instead of number) Invalid file format extension Unsupported template engine name How to Fix Check the allowed values for the setting Verify the type matches what's expected Review the configuration reference documentation Example ❌ Invalid: template_engine = "unknown_engine" ✅ Valid: template_engine = "kida" # default, or "jinja2", "mako", "patitas" C004: Config Type Mismatch Configuration value has wrong type. Common Causes String provided where number expected List provided where single value expected Boolean syntax error How to Fix Check the expected type in documentation Use correct YAML/TOML type syntax C005: Config Defaults Missing Required default configuration could not be loaded. Common Causes Bengal installation is corrupted Custom defaults file is missing How to Fix Reinstall Bengal: pip install --force-reinstall bengal Check that default config files exist in installation C006: Config Environment Unknown Specified environment configuration not found. Common Causes Typo in environment name Environment config file missing How to Fix Check available environments in bengal.toml Create the environment config if needed C007: Config Circular Reference Configuration contains circular references. Common Causes Config A includes B, which includes A Self-referencing configuration value How to Fix Review configuration includes and references Break the circular dependency C008: Config Deprecated Key Configuration uses a deprecated key. Common Causes Using old configuration format Key was renamed in newer version How to Fix Check the migration guide for the new key name Update configuration to use current syntax Discovery Errors (Dxxx) D001: Content Directory Not Found The content directory could not be located. Bengal could not find the content directory specified in your configuration. Without content, there's nothing to build. Common Causes Running bengal from wrong directory Content directory was renamed or moved Typo in content_dir configuration How to Fix Verify you're in the site root directory Check that content/ directory exists Run bengal init to create site structure D002: Invalid Content Path Content path contains invalid characters or structure. Common Causes Special characters in file/folder names Path too long for filesystem Symbolic link issues How to Fix Use only alphanumeric characters, hyphens, and underscores Keep paths reasonably short Avoid symbolic links in content directory D003: Section Index Missing A content section is missing its _index.md file. Common Causes Section folder created without index Index file accidentally deleted How to Fix Create _index.md in the section folder Add required frontmatter with title D004: Circular Section Reference Sections reference each other in a loop. Common Causes Section A's parent is B, but B's parent is A Symbolic links creating loops How to Fix Review section hierarchy Remove circular parent references D005: Duplicate Page Path Multiple pages have the same URL. Two or more pages are configured to output to the same URL. This would cause one to overwrite the other. Common Causes Duplicate slugs in frontmatter Conflicting autodoc output paths Multiple index files in same directory How to Fix Give each page a unique slug Check autodoc configuration for conflicts Remove duplicate content files D006: Invalid File Pattern File pattern in configuration is invalid. Common Causes Malformed glob pattern Unsupported pattern syntax How to Fix Check glob pattern syntax Test pattern with bengal explain patterns D007: Permission Denied Cannot access file or directory due to permissions. Common Causes File owned by different user Read permissions not set File system mounted read-only How to Fix Check file permissions: ls -la Fix permissions: chmod 644 filename Verify filesystem is not read-only Graph Errors (Gxxx) G001: Graph Not Built Attempted to query graph before it was built. Common Causes Calling graph functions before build() Build failed silently How to Fix Ensure site.build() completes before graph queries Check for earlier build errors G002: Graph Invalid Parameter Invalid parameter passed to graph function. Common Causes Page ID doesn't exist Invalid depth or limit value How to Fix Verify page IDs exist in the graph Use positive integers for depth/limit G003: Graph Cycle Detected Circular reference detected in page relationships. Common Causes Page A links to B, B links to A as prerequisite Circular navigation structure How to Fix Review page relationships Break the cycle by removing one reference G004: Graph Disconnected Component Pages are not reachable from navigation. Common Causes Orphan pages without parent section Missing navigation links How to Fix Add pages to appropriate sections Create navigation links to disconnected pages G005: Graph Analysis Failed Graph analysis computation failed. Common Causes Graph is too large Memory constraints Invalid graph state How to Fix Reduce graph size if possible Increase available memory Rebuild the site from scratch Content Errors (Nxxx) N001: Frontmatter Invalid Cannot parse frontmatter in content file. The frontmatter (YAML between --- delimiters) in a content file contains syntax errors and cannot be parsed. Common Causes Missing closing --- delimiter Invalid YAML syntax in frontmatter Tabs instead of spaces for indentation Special characters not properly quoted How to Fix Check that frontmatter has both opening and closing --- Validate YAML syntax in the frontmatter Ensure dates are in ISO format (YYYY-MM-DD) Quote values with special characters Example ❌ Invalid: --- title: My Post date: yesterday # Invalid date --- ✅ Valid: --- title: My Post date: 2024-01-15 --- N002: Frontmatter Date Invalid Date value in frontmatter cannot be parsed. Common Causes Non-standard date format Invalid date (e.g., February 30) Timezone parsing issue How to Fix Use ISO format: YYYY-MM-DD Optionally add time: YYYY-MM-DDTHH:MM:SS Verify the date is valid N003: Content File Encoding File uses unsupported character encoding. Common Causes File saved in non-UTF-8 encoding Binary data in text file Corrupted file How to Fix Convert file to UTF-8: iconv -f LATIN1 -t UTF-8 file.md Re-save file with UTF-8 encoding in your editor Check for binary content N004: Content File Not Found Referenced content file does not exist. Common Causes Typo in filename reference File was moved or deleted Case sensitivity mismatch How to Fix Verify the file path is correct Check for case sensitivity issues Restore or recreate the file N005: Content Markdown Error Markdown parsing failed. Common Causes Malformed markdown syntax Unclosed code blocks Invalid HTML embedded in markdown How to Fix Check for unclosed code fences (```) Validate embedded HTML Use a markdown linter N006: Content Shortcode Error Shortcode in content failed to render. Common Causes Invalid shortcode syntax Missing required shortcode argument Shortcode function raised error How to Fix Check shortcode syntax: {{ }} Verify all required arguments are provided Review shortcode documentation N007: Content TOC Extraction Error Failed to extract table of contents. Common Causes Invalid heading structure Heading without text Parser error How to Fix Ensure headings have text content Use proper heading hierarchy (h1 → h2 → h3) N008: Content Taxonomy Invalid Invalid taxonomy value in frontmatter. Common Causes Taxonomy value is not a list Invalid taxonomy name Taxonomy not defined in config How to Fix Use list syntax for taxonomies: tags: [a, b, c] Check taxonomy is defined in config Verify taxonomy value format N009: Content Weight Invalid Weight value must be a number. Common Causes Weight is a string instead of number Weight contains non-numeric characters How to Fix Use integer for weight: weight: 10 Remove quotes around weight value N010: Content Slug Invalid Slug contains invalid characters. Common Causes Spaces in slug Special characters Non-ASCII characters How to Fix Use only lowercase letters, numbers, and hyphens Example: slug: my-page-title Parsing Errors (Pxxx) P001: YAML Parse Error YAML file contains syntax errors. Common Causes Indentation with tabs instead of spaces Missing colon after key Unquoted special characters How to Fix Use spaces for indentation (2 or 4 spaces) Ensure colons after keys: key: value Quote special values: title: "My: Title" P002: JSON Parse Error JSON file contains syntax errors. Common Causes Trailing comma in array or object Missing quotes around keys Single quotes instead of double How to Fix Remove trailing commas Use double quotes for strings Validate with python -m json.tool file.json P003: TOML Parse Error TOML file contains syntax errors. Common Causes Invalid table syntax Missing quotes around strings with spaces Incorrect date format How to Fix Use [section] for tables Quote strings with spaces Use RFC 3339 date format P004: Markdown Parse Error Markdown file cannot be parsed. Common Causes Unclosed code blocks Invalid HTML Corrupted file How to Fix Check for unclosed ``` code fences Validate embedded HTML Check file encoding P005: Frontmatter Delimiter Missing Content file is missing frontmatter delimiters. Common Causes Missing opening --- Missing closing --- Extra whitespace before delimiter How to Fix Ensure file starts with --- Add closing --- after frontmatter Remove whitespace before first delimiter Example ✅ Correct: --- title: My Page --- Content starts here. P006: Glossary Parse Error Glossary file contains errors. Common Causes Invalid glossary format Missing required fields Duplicate term definitions How to Fix Check glossary file format Ensure each term has required fields Remove duplicate definitions Rendering Errors (Rxxx) R001: Template Not Found Template file could not be located. Bengal could not find the specified template file. This usually happens when a page requests a template that doesn't exist. Common Causes Typo in template name in frontmatter Template file not in templates/ directory Theme template not found Case sensitivity issue (templates/Page.html vs page.html) How to Fix Check the template name in your page's frontmatter Verify the template file exists in templates/ or theme Check for case sensitivity in the filename Run bengal explain templates to see available templates Example ❌ Frontmatter referencing missing template: --- layout: custom-page # This template doesn't exist --- ✅ Using existing template: --- layout: page # This template exists --- R002: Template Syntax Error Jinja2/template syntax error. The template contains a syntax error that prevents it from being parsed. This is usually a Jinja2 syntax issue. Common Causes Missing {% end %} or {% endfor %} Unclosed {{ or {% tags Invalid filter syntax Mismatched block names How to Fix Check the line number in the error message Ensure all blocks have matching end tags Verify filter syntax: {{ value | filter }} Check for unclosed variable tags Example ❌ Missing end tag: {% if page.draft %} Draft content {# Missing {% end %} #} ✅ Correct: {% if page.draft %} Draft content {% end %} R003: Template Undefined Variable Variable used in template is not defined. Common Causes Typo in variable name Variable not passed to template context Using variable before it's set How to Fix Check spelling of variable name Verify variable is in template context Use {{ variable | default("") }} for optional variables R004: Template Filter Error Template filter raised an error. Common Causes Passing wrong type to filter Filter not registered Filter function raised exception How to Fix Check filter expects the input type you're providing Verify custom filters are registered Review filter documentation R005: Template Include Error Could not include referenced template. Common Causes Included template doesn't exist Circular include detected Include path is incorrect How to Fix Verify included template path Check for circular includes Use relative path from templates/ directory R006: Template Macro Error Macro definition or call failed. Common Causes Macro not defined Wrong number of arguments Macro raised error How to Fix Ensure macro is imported: {% from "macros.html" import mymacro %} Check macro signature matches call Review macro implementation R007: Template Block Error Template block inheritance error. Common Causes Block name mismatch with parent Missing parent template Invalid block nesting How to Fix Verify block names match parent template Check parent template exists Ensure blocks are not nested incorrectly R008: Template Context Error Template context is invalid or corrupted. Common Causes Custom context processor raised error Conflicting context values Memory issue with large context How to Fix Review custom context processors Check for conflicting variable names Reduce context size if very large R009: Template Inheritance Error Template inheritance chain is invalid. Common Causes Parent template not found Circular inheritance Invalid extends syntax How to Fix Verify parent template exists Check for circular inheritance Use correct syntax: {% extends "base.html" %} R010: Render Output Error Failed to write rendered output. Common Causes Disk full Permission denied Invalid output path How to Fix Check available disk space Verify write permissions on output directory Check output path is valid Server Errors (Sxxx) S001: Server Port In Use The requested port is already in use. Common Causes Another bengal server running Different application using the port Previous server didn't shut down cleanly How to Fix Use a different port: bengal serve --port 8001 Find and stop the process using the port Wait for port to be released (can take ~30 seconds) S002: Server Bind Error Could not bind to the network interface. Common Causes Permission denied for port < 1024 Network interface doesn't exist Firewall blocking How to Fix Use port >= 1024 (no sudo required) Check bind address is valid Review firewall settings S003: Server Reload Error Live reload failed to trigger. Common Causes WebSocket connection lost Browser extension blocking File watcher issue How to Fix Refresh browser manually Disable browser extensions temporarily Restart the dev server S004: Server WebSocket Error WebSocket connection for live reload failed. Common Causes Proxy not configured for WebSocket Browser doesn't support WebSocket Network issue How to Fix Configure proxy to forward WebSocket Try a different browser Check network connectivity S005: Server Static File Error Could not serve static file. Common Causes File doesn't exist Permission denied Path traversal blocked How to Fix Verify file exists in static/ directory Check file permissions Use valid relative paths only Template Function Errors (Txxx) T001: Shortcode Not Found Referenced shortcode is not registered. Common Causes Typo in shortcode name Shortcode not defined Shortcode file not loaded How to Fix Check shortcode name spelling Verify shortcode is defined in shortcodes/ directory Run bengal explain shortcodes to list available shortcodes T002: Shortcode Argument Error Shortcode received invalid arguments. Common Causes Missing required argument Wrong argument type Unknown argument name How to Fix Check shortcode documentation for required arguments Verify argument types match expected Remove unknown arguments T003: Shortcode Render Error Shortcode execution failed. Common Causes Shortcode code raised exception Invalid return value Template error in shortcode How to Fix Check shortcode implementation Review error message for details Test shortcode in isolation T004: Directive Not Found Referenced directive is not registered. Common Causes Typo in directive name Directive not defined Using MyST syntax for unregistered directive How to Fix Check directive name spelling Verify directive is registered Review available directives in documentation T005: Directive Argument Error Directive received invalid arguments. Common Causes Missing required argument Invalid argument format Argument value out of range How to Fix Check directive documentation Provide all required arguments Use correct argument format T006: Directive Since Empty The {since} directive requires a version parameter. How to Fix Provide a version string: {since}`v2.0` T007: Directive Deprecated Empty The {deprecated} directive requires a version parameter. How to Fix Provide a version string: {deprecated}`v1.5` T008: Directive Changed Empty The {changed} directive requires a version parameter. How to Fix Provide a version string: {changed}`v2.1` T009: Directive Include Not Found The included file in directive was not found. Common Causes Typo in file path File doesn't exist Incorrect relative path How to Fix Verify file path is correct Check file exists at specified location Use path relative to content directory T010: Icon Not Found An icon referenced in frontmatter, directive, or inline syntax does not exist in the icon search path. Bengal searches these directories in order: Site theme icons: themes/{theme}/assets/icons/ in your project Theme icons: Icons bundled with the theme Parent theme icons: If your theme extends another Bengal defaults: Phosphor icons (unless extend_defaults: false) Common Causes Typo in icon name (e.g., icon: warnng instead of icon: warning) Using an icon that hasn't been added to your theme Referencing a Phosphor icon name that differs from Bengal's naming Using extend_defaults: false without providing all needed icons How to Fix Run bengal icons to list available icons Fix typos in icon names Add custom icons to themes/{theme}/assets/icons/ Adding Custom Icons Create an icons directory in your theme: themes/my-theme/assets/icons/ ├── my-custom-icon.svg # New icon └── warning.svg # Overrides default See Icon Reference for SVG format requirements and configuration options. Asset Errors (Xxxx) X001: Asset Not Found Static asset file could not be located. Common Causes Typo in asset path Asset file missing Case sensitivity mismatch How to Fix Check asset path in template or content Verify file exists in static/ directory Check for case sensitivity issues X002: Asset Invalid Path Asset path contains invalid characters. Common Causes Path traversal attempt (../) Special characters in path Absolute path used How to Fix Use relative paths only Remove special characters Don't use .. in asset paths X003: Asset Processing Failed Asset pipeline processing failed. Common Causes Invalid image format Processing tool not available Memory limit exceeded How to Fix Verify asset file is valid Install required processing tools Reduce asset size or processing complexity X004: Asset Copy Error Failed to copy asset to output directory. Common Causes Permission denied Disk full Target file locked How to Fix Check write permissions on output directory Free up disk space Close applications that may lock files X005: Asset Fingerprint Error Failed to generate asset fingerprint/hash. Common Causes File read error Very large file Memory issue How to Fix Check file is readable Reduce file size if very large Increase available memory X006: Asset Minify Error Asset minification failed. Common Causes Invalid CSS/JS syntax Minifier not available Unsupported features in source How to Fix Validate CSS/JS syntax Install minification dependencies Check for syntax not supported by minifier Getting Help If you encounter an error: Check the error message and suggestion in the CLI output Search this page for the error code (Ctrl+F / Cmd+F) Review the troubleshooting steps above Check the troubleshooting guide For bugs or unclear errors, please open an issue.

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

Metadata:
- Author: lbliii
- Word Count: 3543
- Reading Time: 18 minutes