← Back to ColdFusion Administrator Reference

Debugging & Logging - Debugger

Configure line-by-line debugging, breakpoints, and IDE integration

Last updated: October 27, 20257 min read

Overview

The ColdFusion Debugger enables line-by-line step-through debugging of CFML code, allowing developers to pause execution at specific points (breakpoints), inspect variable values, step through code one line at a time, and trace program flow in detail. This is far more powerful than using debug output or logging, as it provides complete control over code execution and visibility into application state.

The debugger integrates with compatible IDEs like Adobe ColdFusion Builder, Eclipse, and VSCode (with extensions), providing a familiar debugging experience similar to other programming languages. Proper debugger configuration is essential for efficient troubleshooting of complex issues.

Configuration Settings

Control debugger behavior and security settings.

Enable Debugger

PurposeActivate debugger support in ColdFusion

DefaultDisabled

RecommendationEnable only in development environments

Performance ImpactMinimal when not actively debugging

Security Critical: MUST be disabled in production - security risk and performance impact. Never enable debugger on production servers.

Debugger Port

PurposeTCP port for IDE to connect to debugger

Default5005

ConfigurationMust match IDE debugger configuration

FirewallEnsure port is accessible from IDE (may need SSH tunnel)

Best Practice: Restrict port access to developer IPs only. Consider changing from default port for obscurity. Use SSH tunnels for secure remote debugging.

Allowed IP Addresses

PurposeRestrict debugger connections to specific IPs

FormatComma-separated list of IPs or ranges

RecommendationAlways include 127.0.0.1 for local debugging

Security Critical: Prevents unauthorized debugging access. Add remote developer IPs carefully. Never use 0.0.0.0 or allow all IPs.

Max Simultaneous Sessions

PurposeLimit number of concurrent debug sessions

Default5

Recommendation2-5 for development servers

ImpactEach session consumes server resources

Debugger Features

The ColdFusion debugger provides powerful capabilities for analyzing code execution.

Breakpoint Management

Line Breakpoints

Pause execution at specific line of code

Conditional Breakpoints

Break only when condition is true (e.g., userID = 123)

Function Breakpoints

Break on function entry

Exception Breakpoints

Break when exception thrown, even if caught by try/catch

Hit Count

Break after breakpoint hit N times

Temporary Breakpoints

Break once then automatically remove

Enabled/Disabled

Toggle breakpoints without removing them

Step-Through Debugging

Step Into

Enter function calls to debug internal logic

Step Over

Execute line without entering functions

Step Out

Complete current function and return to caller

Continue

Resume execution until next breakpoint

Run to Cursor

Execute up to specific line

Restart

Restart request from beginning (if supported)

Variable Inspection

Local Variables

View all variables in current scope

Watch Expressions

Monitor specific variables or expressions

Call Stack

View function call hierarchy and trace execution path

Evaluate Expression

Execute expressions in current context

Modify Values

Change variable values during debugging

Complex Objects

Drill into structures, arrays, CFCs

Remote Debugging Setup

Server Configuration

Required Steps:

Enable debugger in ColdFusion Administrator
Configure debugger port (default 5005)
Add developer IP addresses to allowed list
Ensure firewall allows debugger port
Restart ColdFusion after configuration changes

SSH Tunnel for Secure Remote Debugging

PurposeSecurely access debugger without exposing port

Commandssh -L 5005:localhost:5005 user@server

IDE ConfigurationConnect to localhost:5005

BenefitsEncrypted connection, no firewall changes needed

Best Practice: Preferred method for remote debugging. Provides security without requiring firewall rule changes.

Network Configuration

Security Recommendations:

Verify debugger port is not blocked by firewall
Use VPN for remote access if possible
Avoid exposing debugger port to public internet
Consider port forwarding through bastion hosts

IDE Integration

The ColdFusion debugger integrates with popular development environments.

ColdFusion Builder

Native Support: Built-in CF debugger integration
Configuration: Server connection with debugger port
Features: Full breakpoint support, variable inspection

Designed specifically for CFML debugging with comprehensive feature support.

Eclipse

Plugin Required: Install CF plugin for Eclipse
Debug Perspective: Familiar Eclipse debugging interface
Integration: Use existing Eclipse debugging features

Create debug configuration for CF server to enable debugging.

VS Code

Extension: Install CF debugger extension
Configuration: launch.json configuration file
Features: Modern debugging UI, good performance

Community-driven extensions with improving support for CFML debugging.

IntelliJ IDEA

Plugin: ColdFusion plugin available
Debugging: Use IntelliJ debugging interface
Configuration: Remote debugging setup

Powerful IDE with CF support for comprehensive development workflow.

Best Practices

Development Environment

Enable debugger only on development servers
Use localhost or VPN for debugger access
Set breakpoints strategically in complex code
Use conditional breakpoints to reduce breaks
Remove or disable breakpoints before committing code
Document complex debugging sessions for team

Security Considerations

Critical Security Requirements:

NEVER enable debugger in production
Restrict debugger access by IP address
Use SSH tunnels for remote debugging
Audit debugger access logs regularly
Disable debugger when not actively debugging
Change debugger port from default for obscurity

Performance

Debugging pauses request execution completely
Don't debug high-traffic pages in shared dev environments
Consider dedicated debugging server for complex issues
Disable debugger when doing performance testing
Remove breakpoints when debugging session complete

Effective Debugging Strategies

Systematic Approach:

Set breakpoint at suspected problem area
Step through code to understand flow
Inspect variable values at each step
Use watch expressions for key variables
Check call stack to understand execution path
Test fix, then restart debugging to verify

Common Issues and Solutions

Unable to Connect to Debugger

Symptom: IDE fails to establish debugger connection

Solutions:

Verify debugger enabled in Administrator
Check port and IP configuration
Ensure firewall allows debugger port
Try telnet to debugger port from IDE machine: telnet server 5005
Restart ColdFusion after configuration changes

Breakpoints Not Working

Symptom: Code doesn't pause at breakpoints

Solutions:

Clear template cache in Administrator
Verify correct file being executed (check file path)
Ensure IDE file path matches server file path
Disable trusted cache during debugging
Verify breakpoint is on executable line (not comment or blank line)

Debugger Connection Lost

Symptom: Debugging session disconnects unexpectedly

Solutions:

Increase request timeout in Administrator
Check network stability between IDE and server
Set longer timeout for debugging sessions using <cfsetting requestTimeout>
Use automatic reconnection feature if IDE supports it
Ensure server hasn't restarted during debugging

Cannot Inspect Variable Values

Symptom: Variables show as undefined or unavailable

Solutions:

Verify variable exists in current scope
Check execution point - variable may not be defined yet
Ensure variable hasn't been optimized away by compiler
Move breakpoint to line after variable definition
Use evaluate expression to check variable explicitly

Slow Performance During Debugging

Symptom: Application very slow when debugger enabled

Solutions:

Remove unnecessary breakpoints (each adds slight overhead)
Disable debugger when not actively debugging
Reduce max simultaneous sessions
Avoid inspecting very large complex objects
Use conditional breakpoints instead of many regular breakpoints

Advanced Debugging Techniques

Leverage advanced features for more efficient debugging.

Conditional Breakpoints

Break only when specific condition true (e.g., userID = 123). Reduces interruptions in loops or frequently called functions.

Expression Evaluation

Execute CFML code in context of current breakpoint. Test fixes without restarting request.

Hot Code Reload

Some IDEs support changing code during debug session. Limited support in CF compared to Java.

Exception Breakpoints

Automatically break when any exception thrown. Excellent for finding root cause of errors.

Debugging Workflows

Debugging Logic Errors

Systematic Workflow:

Set breakpoint before suspected problem area
Step through code line by line
Watch variable values change
Identify where logic deviates from expected
Fix and verify with another debug session

Debugging Performance Issues

Performance Analysis:

Set breakpoint at start of slow operation
Step through to identify slow sections
Check database query times
Identify loops executing excessively
Profile with debug output after narrowing scope

Debugging Integration Issues

Integration Testing:

Set breakpoint before external service call
Inspect request data being sent
Step into call to see response handling
Check response data structure
Verify error handling logic

Alternatives to Line Debugger

Other debugging approaches for different scenarios.

Debug Output

Use Case: Simpler than line debugging for many scenarios
Features: Shows database queries, timing, variables

No IDE configuration required. See separate Debug Output Settings page.

Logging with cflog

Use Case: Log variable values and execution points
Benefits: Safe for production (with appropriate log levels)

Good for intermittent issues. Review logs after request completes.

cfdump to File

Use Case: Dump complex variables to file
Benefits: No breakpoint interruption

Useful for multi-step processes. Review output at leisure.

FusionReactor Profiler

Use Case: Production-safe performance profiling
Features: Detailed metrics, historical data and trends

Commercial APM tool with comprehensive monitoring capabilities.

Related Resources

Debug Output SettingsAlternative debugging approach with request information and variable display Debug IP AddressesIP filtering configuration for debug output Logging SettingsLog file configuration and management Server SettingsRequest timeout settings and server configuration ColdFusion Administrator ReferenceComplete administrator guide and settings reference