# Troubleshooting

This guide covers common issues you might encounter when using DocBox and their solutions.

## 🚨 Common Errors

### "Output directory does not exist"

**Error Message:**

```
The output directory [/path/to/docs] does not exist
```

**Cause:** The specified output directory doesn't exist on the filesystem.

**Solution:** Create the output directory before running DocBox, or ensure that the path is correct. You can create it manually or programmatically:

```javascript
// Option 1: Create the directory first
directoryCreate( expandPath( "/docs" ), true );

// Option 2: Use an existing directory
new docbox.DocBox()
    .addStrategy( "HTML", {
        outputDir: expandPath( "/existing/path" )
    } )
    .generate( source: "/src", mapping: "app" );
```

### Missing Source Mappings (CLI)

**Error Message:**

```
❌ ERROR: No valid source mappings found.
```

**Cause:** The BoxLang CLI command wasn't provided with source directory information.

**Solution:** Ensure you provide either:

* `--source` and `--mapping` together
* One or more `--mappings:<name>=<path>` options
* JSON array via `--source`

```bash
# Correct usage
boxlang module:docbox --source=/src --mapping=app --output-dir=/docs

# Or with mappings
boxlang module:docbox --mappings:app=/src --output-dir=/docs
```

### "Cannot read properties of undefined (reading 'toLowerCase')"

**Cause:** JavaScript error in HTML templates when filtering methods with missing properties.

**Solution:** This was fixed in DocBox 5.0. Update to the latest version:

```bash
box update docbox
```

### Class Not Found

**Error Message:**

```
Class [myapp.MyClass] not found
```

**Cause:** The mapping specified doesn't match the actual package structure.

**Solution:** Ensure your mapping matches your component path structure:

```javascript
// If your component is at: /src/models/User.cfc
// And its component declaration is: component { }
// And you access it via: new models.User()

new docbox.DocBox()
    .addStrategy( "HTML", { outputDir: "/docs" } )
    .generate(
        source  = expandPath( "/src" ),      // Source directory
        mapping = "models"                    // Base mapping
    );
```

### Exclusion Pattern Not Working

**Problem:** Files are still being documented despite exclusion pattern.

**Cause:** Exclusion patterns are applied to relative file paths, not absolute paths.

**Solution:** Use patterns that match the relative path structure:

```javascript
// Correct - matches relative paths
excludes = "(tests|build|\.git)"

// Incorrect - won't match absolute paths
excludes = "/full/path/to/tests"
```

## 🔍 Metadata Issues

### Empty Documentation Pages

**Problem:** Generated docs show components but no methods/properties.

**Cause:** Components lack JavaDoc comments or metadata.

**Solution:** Add proper documentation to your components:

```javascript
/**
 * User management service
 *
 * @author Your Name
 */
component {

    /**
     * Gets a user by ID
     *
     * @id The user ID
     * @return User object or null
     */
    public function getUser( required numeric id ) {
        // implementation
    }
}
```

### Generic Types Not Showing

**Problem:** Generic type annotations like `Array<User>` not appearing in docs.

**Cause:** Using standard `@returntype` instead of `@doc.type`.

**Solution:** Use the `@doc.type` annotation:

```javascript
/**
 * Gets all active users
 *
 * @return Array of User objects
 * @doc.type Array<User>
 */
public array function getUsers() {
    return [];
}
```

### Implements Not Detected

**Problem:** Interface implementations not showing in documentation.

**Cause:** Engine-specific metadata format differences.

**Solution:** DocBox 5.0+ handles both formats automatically. If using older versions, update:

```bash
box update docbox
```

## 🎨 HTML/UI Issues

### Dark Mode Not Persisting

**Problem:** Dark mode preference resets on page reload.

**Cause:** Browser localStorage might be disabled or cleared.

**Solution:**

1. Check browser console for localStorage errors
2. Enable localStorage in browser settings
3. Clear site data and try again

### Search Not Working

**Problem:** Method search doesn't filter results.

**Cause:** JavaScript not loading or Alpine.js initialization issue.

**Solution:**

1. Check browser console for errors
2. Ensure you're using a modern browser (Chrome, Firefox, Edge, Safari)
3. Clear browser cache and reload
4. Check network tab for failed asset loads

### Theme Not Loading

**Problem:** Documentation appears unstyled or broken.

**Cause:** Asset paths incorrect or theme not specified properly.

**Solution:**

```javascript
// Explicitly specify theme
new docbox.DocBox()
    .addStrategy( "HTML", {
        outputDir: "/docs",
        theme: "default"  // or "frames"
    } )
    .generate( source: "/src", mapping: "app" );
```

## 🛠️ Build Issues

### CLI Command Not Found

**Error Message:**

```
Command [module:docbox] not found
```

**Cause:** bx-docbox module not installed.

**Solution:**

```bash
# For CommandBox web runtimes
box install bx-docbox

# For BoxLang OS runtime
install-bx-module bx-docbox

# Verify installation
boxlang module:docbox --version
```

### Memory Issues with Large Codebases

**Problem:** DocBox runs out of memory when processing large projects.

**Solution:**

1. Increase JVM heap size

```bash
box config set server.jvm.heapSize=1024
```

1. Process in smaller chunks:

```javascript
// Document modules separately
new docbox.DocBox()
    .addStrategy( "HTML", { outputDir: "/docs/module1" } )
    .generate( source: "/src/module1", mapping: "module1" );

new docbox.DocBox()
    .addStrategy( "HTML", { outputDir: "/docs/module2" } )
    .generate( source: "/src/module2", mapping: "module2" );
```

1. Use more aggressive exclusion patterns:

```javascript
excludes = "(tests|specs|build|node_modules|\.git|vendor)"
```

### Build Hangs or Takes Too Long

**Problem:** Documentation generation appears to hang.

**Cause:** Processing too many files or infinite recursion in inheritance.

**Solution:**

1. Add verbose logging to see progress
2. Check for circular dependencies in your code
3. Exclude unnecessary directories
4. Run in smaller batches

## 🦤 BoxLang-Specific Issues

### BoxLang Module Not Loading

**Problem:** Module loads but CLI command errors out.

**Cause:** Module registration issue or conflicts.

**Solution:**

```bash
# Reinstall the module
box uninstall bx-docbox
box install bx-docbox

# Or force module reload
box reload
```

### Metadata Format Differences

**Problem:** Documentation differs between CFML and BoxLang engines.

**Cause:** BoxLang uses different metadata structure for some properties.

**Solution:** DocBox 5.0+ automatically handles both formats. If you're on an older version:

```bash
box update docbox
```

## 📊 Strategy-Specific Issues

### JSON Output Empty

**Problem:** JSON files generated but contain no data.

**Cause:** Source directory or mapping incorrect.

**Solution:** Verify your paths and mappings:

```javascript
new docbox.DocBox()
    .addStrategy( "JSON", {
        projectTitle: "My API",
        outputDir: expandPath( "/docs/json" )
    } )
    .generate(
        source: expandPath( "/src" ),  // Use expandPath()
        mapping: "app"
    );
```

### XMI/UML Strategy Fails

**Problem:** XMI strategy throws errors.

**Cause:** Missing or invalid output file path.

**Solution:**

```javascript
new docbox.DocBox()
    .addStrategy( "XMI", {
        outputFile: expandPath( "/docs/diagram.uml" )  // Not outputDir!
    } )
    .generate( source: "/src", mapping: "app" );
```

## 🔧 Debug Tips

### Enable Verbose Logging

Add debugging output to your generation script:

```javascript
try {
    var docbox = new docbox.DocBox()
        .addStrategy( "HTML", {
            outputDir: expandPath( "/docs" )
        } );

    writeDump( "Starting documentation generation..." );

    docbox.generate(
        source: expandPath( "/src" ),
        mapping: "app"
    );

    writeDump( "Generation complete!" );
} catch ( any e ) {
    writeDump( var=e, label="DocBox Error" );
    rethrow;
}
```

### Check Component Metadata

Verify your component metadata is readable:

```javascript
component = createObject( "component", "myapp.MyClass" );
metadata = getComponentMetadata( component );
writeDump( metadata );
```

### Validate Output Directory Permissions

Ensure DocBox can write to the output directory:

```javascript
testFile = expandPath( "/docs/test.txt" );
fileWrite( testFile, "test" );
fileDelete( testFile );
writeDump( "Output directory is writable" );
```

## 📞 Getting Help

If you're still experiencing issues:

1. **Check Documentation**: [docbox.ortusbooks.com](https://docbox.ortusbooks.com/)
2. **Search Issues**: [Jira Issue Tracker](https://ortussolutions.atlassian.net/projects/DOCBOX)
3. **Community Forums**: [Ortus Community](https://community.ortussolutions.com/)
4. **CFML Slack**: #box-products channel at [cfml-slack.herokuapp.com](http://cfml-slack.herokuapp.com/)
5. **Professional Support**: [Ortus Solutions](https://www.ortussolutions.com/services/support)

## 📝 Reporting Bugs

When reporting issues, please include:

* DocBox version (`box info docbox` or `boxlang module:docbox --version`)
* CFML engine and version
* Operating system
* Complete error message and stack trace
* Minimal code example to reproduce
* Expected vs actual behavior


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docbox.ortusbooks.com/getting-started/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.