# Troubleshooting URL: /bengal/docs/ship/troubleshooting/ Section: troubleshooting Tags: persona-operator -------------------------------------------------------------------------------- Troubleshooting Diagnose and fix common Bengal build, template, and configuration issues. Note Note Do I need this? Use when a build fails, templates error, or output looks wrong. For proactive checks before deploy, see Content Validation. Warning Template Errors Diagnosing and fixing template syntax errors, undefined variables, and missing templates 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: 466 - Reading Time: 2 minutes