Troubleshooting

Common issues and solutions when using DocBox

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:

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

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

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:

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

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

/**
 * 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:

/**
 * 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:

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:

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

# 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

box config set server.jvm.heapSize=1024

1. Process in smaller chunks:

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

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:

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

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:

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:

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:

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:

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

Validate Output Directory Permissions

Ensure DocBox can write to the output directory:

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

2. Search Issues: Jira Issue Tracker

3. Community Forums: Ortus Community

4. CFML Slack: #box-products channel at cfml-slack.herokuapp.com

5. Professional Support: Ortus Solutions

📝 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