# Troubleshooting

URL: /bengal/docs/0.5.0/building/troubleshooting/
Section: troubleshooting

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

Troubleshooting Guides for diagnosing and resolving common Bengal issues. Quick Diagnosis # Check configuration bengal config doctor # Run health checks bengal check # Verbose build output bengal build --verbose # Full debug mode bengal build --dev # Explain incremental build decisions (why pages rebuilt/skipped) bengal build --explain # Preview build without writing files bengal build --dry-run Common Issues Template Errors - Syntax errors, undefined variables, and missing templates Build Failures "Content directory not found" Ensure you're running Bengal from your site root directory: cd my-site bengal build "Template not found" Check template search paths in error message Verify template exists in templates/ or theme templates/ Run bengal build --verbose for detailed template resolution Build hangs or is very slow Check for infinite loops in templates Use --profile-templates to identify slow templates For large sites (5K+ pages), use --memory-optimized Server Issues Port already in use # Clean up stale server processes bengal clean --stale-server # Use a different port bengal serve --port 8080 Changes not reflecting Hard refresh browser (Ctrl+Shift+R) Clear browser cache Restart server: bengal serve Cache Issues Stale content after changes # Clear build cache bengal clean --cache # Force full rebuild bengal build --no-incremental Incremental build not detecting changes Run bengal build --explain to see why pages are rebuilt or skipped Check file timestamps Run bengal clean --cache to reset Verify .bengal/ directory exists Too many pages rebuilding Use --explain to diagnose why pages are being rebuilt: bengal build --explain Output shows rebuild reasons per page: content_changed — Page content was modified template_changed — Template file was updated asset_fingerprint_changed — CSS/JS assets changed cascade_dependency — Parent section changed nav_changed — Navigation structure updated The --explain output also includes a Decision Trace showing layer-by-layer debugging info: ═══════════════════════════════════════════════════════════════ DECISION TRACE ═══════════════════════════════════════════════════════════════ Decision: INCREMENTAL ─────────────────────────────────────────────────────────────── Layer 1: Data Files ─────────────────────────────────────────────────────────────── Checked: 3 Changed: 0 Fingerprints available: ✓ ─────────────────────────────────────────────────────────────── Layer 2: Autodoc ─────────────────────────────────────────────────────────────── Sources tracked: 448 Sources stale: 0 Metadata available: ✗ ⚠ Using fingerprint fallback (metadata unavailable) Detection method: fingerprint ─────────────────────────────────────────────────────────────── Layer 3: Section Optimization ─────────────────────────────────────────────────────────────── Sections total: 5 Sections changed: 1 • docs (subsection_changed:about/glossary.md) ─────────────────────────────────────────────────────────────── Layer 4: Page Filtering ─────────────────────────────────────────────────────────────── In changed sections: 35 Filtered out: 1028 ═══════════════════════════════════════════════════════════════ For machine-readable output (CI/tooling): bengal build --explain --explain-json Strict Incremental Mode (Debugging) For debugging cache issues, enable strict incremental mode to surface fallback paths: # Log warnings when fallbacks are used BENGAL_STRICT_INCREMENTAL=warn bengal build # Fail when fallbacks are used (useful for CI) BENGAL_STRICT_INCREMENTAL=error bengal build This helps identify when: Autodoc metadata is missing (fingerprint fallback used) Data file dependencies aren't tracked Cache migration issues occur

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

Metadata:
- Author: lbliii
- Word Count: 425
- Reading Time: 2 minutes