# Troubleshooting

URL: /bengal/docs/ship/troubleshooting/
Section: troubleshooting
Description: Common issues and how to resolve them

---

> For a complete page index, fetch /bengal/llms.txt.

Diagnose and fix common Bengal build, template, and configuration issues.

Note

Do I need this? Use when a build fails, templates error, or output looks
wrong. For proactive checks before deploy, see
Content Validation (/bengal/docs/ship/validate/).

Template Errors

Diagnosing and fixing template syntax errors, undefined variables, and missing templates

(/bengal/docs/ship/troubleshooting/template-errors/)

## Quick Diagnosis

BASH

```
# 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 (./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:

BASH

```
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

BASH

```
# 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

BASH

```
# 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:

BASH

```
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:

plaintext
PLAINTEXT

```
═══════════════════════════════════════════════════════════════
                    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):

BASH

```
bengal build --explain --explain-json
```
### Strict Incremental Mode (Debugging)

For debugging cache issues, enable strict incremental mode to surface fallback paths:

BASH

```
# 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

## In This Section

Template Errors (/bengal/docs/ship/troubleshooting/template-errors/)

Diagnosing and fixing template syntax errors, undefined variables, and missing templates

Related Pages

Configuration (/bengal/docs/ship/configuration/)

Configuring Bengal with bengal.toml

Related

Internationalization (i18n) (/bengal/docs/build-sites/structure/i18n/)

Multi-language sites with gettext PO/MO, RTL support, and translation workflows

Related

Ship (/bengal/docs/ship/)

Build configuration, SEO/discovery, output formats, and deployment

Related

Analysis (/bengal/docs/build-sites/structure/analysis/)

Site structure analysis tools

Related

Versioned Documentation (/bengal/docs/build-sites/structure/versioning/)

Serve multiple versions of your documentation from a single site

Related

persona-operator (/bengal/tags/persona-operator/)