Debugging & Logging - Debugger

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

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 Adobe's official ColdFusion Builder extension for VS Code, which replaced the legacy Eclipse-based ColdFusion Builder, 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.

Allow Line Debugging

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 (Adobe)
ConfigurationMust match the IDE debugger configuration. Adobe also has you specify the port in the JVM settings, for example -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=#portNum#
FirewallEnsure port is accessible from IDE (may need SSH tunnel)
Best Practice: Restrict port access to developer IPs only. Use SSH tunnels for secure remote debugging.

Maximum Simultaneous Debugging Sessions

PurposeLimit number of concurrent debug sessions
Default5 (Adobe)
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 Allow Line Debugging in ColdFusion Administrator
  • Set the debugger port and the maximum number of simultaneous debugging sessions
  • On ColdFusion 2025 Update 12 and later, the debugger binds to 127.0.0.1 by default. To accept remote connections, set -Dcoldfusion.debugger.bindhost to a specific network interface IP (or 0.0.0.0)
  • Restrict the debugger port to developer IPs at the firewall (the Debugger Settings page has no IP allowlist)
  • Ensure firewall allows debugger port
  • Restart ColdFusion after configuration changes

SSH Tunnel for Secure Remote Debugging

PurposeSecurely access debugger without exposing port
Commandssh -L <port>:localhost:<port> user@server (use your debugger port)
IDE ConfigurationConnect to localhost on the forwarded debugger port. With the Update 12 loopback default, a tunnel needs no bindhost change
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

The standalone Eclipse-based ColdFusion Builder is legacy. Adobe now ships ColdFusion Builder as a VS Code extension.

Eclipse

Status
Legacy

The Eclipse-based ColdFusion Builder reached end of life on October 1, 2024. Use the VS Code extension instead.

VS Code

Extension
Adobe ColdFusion Builder for VS Code
Configuration
Server and debug configuration in the extension
Features
Modern debugging UI, good performance

Adobe's official, supported debugging client for ColdFusion, including the line debugger.

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 port access by IP at the firewall
  • Use SSH tunnels for remote debugging
  • Audit debugger access logs regularly
  • Disable debugger when not actively debugging

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 firewall configuration, and on 2025 Update 12 or later check -Dcoldfusion.debugger.bindhost
  • Ensure firewall allows debugger port
  • Try telnet to the debugger port from the IDE machine: telnet server <port>
  • 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

Debugging & Logging - Debugger | ColdFusion Administrator | CFGuide