Debugging & Logging - Debugging Settings
Master control panel for ColdFusion debugging features and security
Overview
The Debugging Settings page is the central control panel for all ColdFusion debugging features. This page enables or disables debugging output globally, controls which debugging information is displayed, configures IP address restrictions, manages robust exception information, and enables the line debugger for step-through debugging in compatible IDEs.
Proper configuration of debugging settings is critical for both development productivity and production security. While debugging tools are invaluable during development, they must be carefully controlled in production environments to prevent information disclosure, maintain performance, and comply with security requirements.
Master Debug Controls
Global settings that enable or disable all debugging features across the ColdFusion server.
Enable Request Debugging Output
PurposeMaster switch to enable/disable all debugging output displayed on pages
DefaultEnabled in development editions, disabled in production
When EnabledDisplays debug information at bottom of HTML pages for allowed IP addresses
Information ShownExecution times, database queries, variable scopes, exceptions, template execution paths
DevelopmentEnable for maximum visibility into application behavior
ProductionDisable to prevent information disclosure and performance impact
Critical Security Warning: Leaving debug output enabled in production can expose database structure, file paths, variable contents, API keys, session data, and internal application logic to potential attackers. This is a serious security vulnerability and compliance violation.
Best Practice: Use IP address filtering if you must enable debugging in production for troubleshooting. Limit to single admin IP, enable only specific debug categories needed, and disable immediately after resolving the issue.
Enable Robust Exception Information
PurposeDisplay detailed error information when unhandled exceptions occur
Information ShownFull stack traces, line numbers, file paths, SQL statements, variable values at error point, Java exception details
DevelopmentEssential - always enable for detailed error debugging
ProductionMUST be disabled without exception
Security ImpactHIGH - Exposes internal application structure and sensitive data
Production Security: This setting should NEVER be enabled in production environments. It reveals file system paths, database details, internal logic, and potentially sensitive data. Use custom error pages and server-side logging instead.
Compliance Impact:
- PCI DSS: Robust exceptions can expose cardholder data - violation of requirement 6.5.5
- HIPAA: May expose PHI in error details - breach of privacy rules
- GDPR: Can expose personal data - violation of data protection requirements
- SOC 2: Fails security controls for information disclosure
Enable Performance Monitoring
PurposeTrack and display performance metrics for requests
Metrics CollectedPage execution time, database query times, memory usage, template processing times
DevelopmentEnable to identify performance bottlenecks early
ProductionDisable or use professional APM tools (FusionReactor, New Relic)
Performance ImpactMinimal overhead in development, but compounds under production load
Production Alternative: Use dedicated Application Performance Monitoring (APM) tools like FusionReactor or SeeFusion for production performance monitoring without security risks.
Enable CFSTAT
PurposeEnable server statistics monitoring via cfstat command-line utility
Information ProvidedReal-time server metrics, request counts, queue lengths, memory usage
Access MethodCommand-line tool:
cfstat (requires server access)Production UseSafe to enable - provides read-only server statistics via CLI
Performance ImpactNegligible - statistics collection is lightweight
Use Case: Helpful for real-time monitoring during performance testing or troubleshooting. Requires SSH/RDP access to server, so no public exposure risk.
Debug Output Template
Control which debugging information is displayed and how it's formatted.
Select Debugging Output Format
PurposeChoose the template that formats debug output display
Available Optionsclassic.cfm (traditional), dockable.cfm (modern floating panel), custom templates
Recommendationdockable.cfm - Modern UI with better developer experience
Custom TemplatesCan create custom debug output templates for specific needs
Dockable Template Benefits:
- Floating panel doesn't interfere with page layout
- Collapsible sections for easier navigation
- Search and filter capabilities
- Copy-to-clipboard functionality
- Moveable and resizable interface
Report Execution Times
PurposeDisplay execution time for each template processed during request
Information ShownTemplate path, execution time in milliseconds, cumulative times
Use CaseIdentify slow templates and includes, find performance bottlenecks
RecommendationEnable in development for performance awareness
Performance Optimization: Use this to identify templates that take disproportionate time. Look for slow includes, excessive nested templates, or templates processing large datasets.
IP Address Restrictions
Limit debugging output to specific IP addresses for security in production-like environments.
Debugging IP Addresses
PurposeRestrict debug output visibility to specific IP addresses
FormatComma-separated list of IPs, wildcards, or CIDR ranges
ExamplesSingle IP:
Wildcard:
CIDR:
Multiple:
192.168.1.100Wildcard:
192.168.1.*CIDR:
192.168.1.0/24Multiple:
127.0.0.1, 192.168.1.100, 10.0.0.*Default BehaviorEmpty list = show debug to ALL users (dangerous in production)
Security Critical: If debug output is enabled and IP list is empty, ALL users see debugging information. Always configure IP restrictions if debugging is enabled in staging or production environments.
Best Practices:
- Always include
127.0.0.1for localhost access - Use specific IPs, not broad ranges, in production
- Consider VPN IP addresses for remote developers
- Test from both allowed and denied IPs to verify filtering
- Document why each IP is whitelisted
- Review and update list regularly (remove departed staff)
Managing IP Address List
ConfigurationCan be managed on this page or dedicated IP Addresses page
ScopeServer-wide setting (applies to all applications)
Load BalancersMay need to configure to pass through real client IP (X-Forwarded-For header)
IPv6 SupportSupport varies by ColdFusion version - test before relying on IPv6 filtering
Load Balancer Configuration: If using a load balancer or reverse proxy, configure it to pass the original client IP address. Otherwise, ColdFusion only sees the load balancer IP, making IP filtering ineffective.
Line Debugger Settings
Configure the line-by-line debugger for step-through debugging in compatible IDEs.
Enable Line Debugger
PurposeEnable step-through debugging with breakpoints in ColdFusion Builder or compatible IDEs
Compatible IDEsAdobe ColdFusion Builder, Eclipse with CFML plugin
CapabilitiesSet breakpoints, step through code line-by-line, inspect variables at runtime, evaluate expressions
DevelopmentEnable for advanced debugging when needed
ProductionMUST be disabled - security risk and performance impact
Performance ImpactModerate when enabled, significant when actively debugging
Security Warning: Line debugger enabled in production allows remote code inspection and could potentially be exploited. Always disable in production environments. Consider security risks even in development if server is network-accessible.
Debugger Port
PurposeNetwork port for IDE to connect to ColdFusion debugger
Default5005
RequirementsPort must be accessible from IDE to ColdFusion server
FirewallMay need to open port in firewall for remote debugging
Security Consideration: Only allow debugger port access from trusted developer workstations. Use firewall rules to restrict access. Never expose debugger port to public internet.
Maximum Simultaneous Debugger Connections
PurposeLimit number of concurrent IDE debugger connections
Default5 connections
RecommendationSet to number of developers who need simultaneous debugging
ImpactEach connection consumes server resources and monitoring threads
Debug Output Details Configuration
Fine-tune which specific debugging information categories are displayed.
Database Activity
- Information
- SQL queries, execution times, record counts
- Development
- Essential for query optimization
- Production
- Never enable - major security risk
Shows all SQL queries with parameters and timing. Critical for identifying N+1 queries and slow database operations.
Exception Information
- Information
- Caught exceptions with stack traces
- Development
- Helpful for tracking handled errors
- Production
- Disable to prevent information leakage
Displays exceptions even when caught by try/catch. Helps identify swallowed errors and exception handling issues.
Tracing Information
- Information
- cftrace output and timing between points
- Development
- Useful for tracking execution flow
- Production
- Disable unless using IP filtering
Shows developer-added trace points for debugging complex logic and measuring performance between checkpoints.
Variable Scopes
- Information
- Contents of URL, Form, Session, Application, etc.
- Development
- Essential for verifying data structures
- Production
- CRITICAL - Never enable, exposes sensitive data
Most sensitive debug category. Can expose passwords, tokens, API keys, and personal data. Huge security risk.
General Debug Information
- Information
- Request metrics, memory usage, cache stats
- Development
- Good for high-level performance monitoring
- Production
- Generally safe but unnecessary with APM tools
Shows overall request timing, template cache statistics, and memory usage. Less sensitive than other categories.
Template Execution
- Information
- Templates processed and their execution times
- Development
- Identify slow templates and includes
- Production
- Can reveal application structure
Template hierarchy with timing helps optimize include structure and identify bottleneck templates.
Environment-Specific Best Practices
Development Environment Settings
Recommended Configuration:
- Enable Request Debugging Output: Yes
- Enable Robust Exception Information: Yes
- Enable Performance Monitoring: Yes
- Debug Output Format: dockable.cfm
- Database Activity: Yes
- Exception Information: Yes
- Tracing Information: Yes
- Variable Scopes: All scopes
- General Debug Information: Yes
- Report Execution Times: Yes
- Line Debugger: Yes (when needed)
- IP Filtering: Not required for local development
Staging/QA Environment Settings
Recommended Configuration:
- Enable Request Debugging Output: Yes with IP filtering
- Enable Robust Exception Information: No (test production behavior)
- Enable Performance Monitoring: Yes
- Debug Output Format: dockable.cfm
- Database Activity: Yes
- Exception Information: Yes
- Tracing Information: Yes
- Variable Scopes: Limited (URL, Form only)
- General Debug Information: Yes
- Line Debugger: No
- IP Filtering: QA team IPs only
Production Environment Settings
Required Configuration:
- Enable Request Debugging Output: NO
- Enable Robust Exception Information: NO
- Enable Performance Monitoring: NO
- Database Activity: NO
- Exception Information: NO
- Tracing Information: NO
- Variable Scopes: NONE
- General Debug Information: NO
- Line Debugger: NO
- Custom Error Pages: YES - Configure via Server Settings
- Error Logging: YES - Log to files, never display
Emergency Production Debugging
If Absolutely Necessary (Extreme Caution):
- Enable Request Debugging Output: Yes
- Enable Robust Exception Information: NO (never)
- Database Activity: Only if database issue
- Exception Information: NO
- Variable Scopes: NONE
- General Debug Information: Yes (relatively safe)
- IP Filtering: Single admin IP ONLY
- Time Limit: Disable within hours, not days
- Documentation: Log in change management system
- Approval: Require manager approval
Security Considerations
Information Disclosure Risks
Debug Output Can Expose:
- File System Paths: Reveals server directory structure and installation paths
- Database Schema: Table names, column names, relationships visible in queries
- SQL Queries: Complete queries with bound parameters may contain sensitive data
- Credentials: Passwords, API keys, tokens in variable scopes
- Session Data: User information, authentication tokens, shopping cart contents
- Business Logic: Application flow, validation rules, security checks
- Stack Traces: Code structure, library versions, potential vulnerabilities
- Configuration: Datasource names, server settings, external service endpoints
- Personal Data: Customer information, PII, PHI in variables or queries
Compliance Requirements
Regulatory Compliance:
- PCI DSS: Debug output exposing cardholder data violates requirement 6.5.5 and 6.5.10. Must be disabled in production payment processing systems.
- HIPAA: PHI exposure in debug output constitutes a breach. Requires Business Associate Agreement violations reporting.
- GDPR: Personal data in debug output violates data protection requirements. May require breach notification to authorities and data subjects.
- SOC 2: Uncontrolled debug output fails security controls for data confidentiality and availability.
- ISO 27001: Information disclosure through debug output violates access control and information security policies.
Performance Impact Analysis
Development Environment
- Impact
- 10-50ms per request
- Memory
- Minimal - acceptable for single user
- Verdict
- Enable all features - benefits outweigh cost
Production Environment
- Impact
- 20-40% performance degradation
- Memory
- Significant - compounds under load
- Verdict
- NEVER enable - unacceptable cost
Line Debugger Active
- Impact
- Severe - request pauses at breakpoints
- Concurrency
- Blocked requests queue waiting for debugger
- Verdict
- Only use in isolated development
Common Issues & Solutions
Debug Output Not Appearing
Symptom: Debugging is enabled but no output shows on pages
Solutions:
- Verify "Enable Request Debugging Output" is checked
- Check your IP address is in allowed IP list (use whatismyip.com)
- Verify you're not using VPN that changes your IP
- Check load balancer is passing real client IP (X-Forwarded-For)
- Confirm request returns HTML (debug doesn't show for JSON/XML/PDF)
- Verify
cfcontentorcfflushnot bypassing debug output - Check for JavaScript errors that might hide dockable debug panel
Debug Output Shows to All Users
Symptom: Debug information visible to end users in production
Immediate Actions:
- IMMEDIATELY disable "Enable Request Debugging Output"
- Verify IP address filtering is configured with specific IPs
- Check that IP list is not empty (empty = all users see debug)
- Review server logs for potential data exposure
- Assess if incident requires security breach notification
- Document incident and implement prevention procedures
- Consider implementing automated checks for debug settings
Line Debugger Won't Connect
Symptom: IDE cannot connect to ColdFusion debugger
Solutions:
- Verify "Enable Line Debugger" is checked in administrator
- Restart ColdFusion after enabling line debugger
- Check firewall allows connections to debugger port (default 5005)
- Verify debugger port in IDE matches ColdFusion configuration
- Confirm server hostname/IP is correct in IDE configuration
- Check for port conflicts with other services
- Review ColdFusion logs for debugger startup errors
Performance Degradation with Debugging
Symptom: Application significantly slower with debug output enabled
Solutions:
- Disable variable scope display (especially Session/Application)
- Use minimum execution time filter to reduce output volume
- Disable database activity if not needed for current debugging
- Switch from classic to dockable format (more efficient)
- Enable only specific debug categories needed for current issue
- Consider using
cflogandcfdump output="file"instead
Alternative Debugging Approaches
File-Based Logging
- Method
- cflog, cfdump output="file"
- Benefits
- Safe for production, no user exposure
- Use Case
- Production debugging and audit trails
Write debugging information to log files accessible only to administrators. Production-safe alternative to debug output.
APM Tools
- Tools
- FusionReactor, SeeFusion, New Relic
- Benefits
- Production-safe, comprehensive metrics
- Features
- Real-time monitoring, alerting, profiling
Professional monitoring tools provide production-safe visibility without security risks of debug output.
Custom Debug Frameworks
- Approach
- Build application-specific debug panels
- Benefits
- Full control, custom authentication
- Effort
- Higher initial development time
Create custom debugging interfaces with your own security controls and exactly the information you need.
Deployment Checklist
Pre-Production Deployment Verification
Mandatory Checks Before Production Deployment:
- Verify "Enable Request Debugging Output" is UNCHECKED
- Verify "Enable Robust Exception Information" is UNCHECKED
- Verify "Enable Line Debugger" is UNCHECKED
- Confirm custom error page is configured for site-wide errors
- Confirm missing template handler is configured
- Test that errors show user-friendly messages (not stack traces)
- Verify error logging is enabled and writing to files
- Confirm log files are secured (not publicly accessible)
- Document debug settings in deployment checklist
- Consider automated tests to verify debug is disabled