Overview
This downloadable resource is a ready-to-use ColdFusion error handler template packaged as a ZIP file. It gives you a production-safe, customizable framework for global exception handling in CFML applications, including a friendly 500 page, centralized logging, optional email alerts, and example hooks for third‑party error tracking. Use it to standardize your onError and try/catch behavior across projects, reduce crash triage time, and protect users from raw stack traces.
The template is carefully structured for Adobe ColdFusion (2018/2021/2023) and Lucee (5.3+/6.x), with code samples, configuration files, and documentation that help you implement robust exception handling in minutes.
What You’ll Get
- Application.cfc
- Prewired onError(), onMissingTemplate(), and secure defaults for exception handling.
- Simple logging and environment toggles (dev vs. prod).
- /errors/
- 500.cfm: user-friendly internal error page with optional troubleshooting details.
- 404.cfm: not-found handler with safe messaging.
- email-error.cfm: HTML email template for exception alerts.
- error.css: minimal styles for consistent presentation.
- /lib/
- Logger.cfc: helper for file logging and message formatting.
- /tests/
- throw.cfm: intentionally triggers errors to validate the handler.
- missing.cfm: simulates missing templates for 404 behavior.
- /config/
- error-handler.json: configuration for email recipients, log file name, debug mode, and data redaction keys.
- README.pdf (6–8 pages)
- Installation, configuration, and troubleshooting guide with screenshots.
- LICENSE.txt
- Permissive license for commercial and personal projects.
- CHANGELOG.md
- Notes on improvements and compatibility updates.
Supported Environments
- CFML engines
- Adobe ColdFusion 2018, 2021, 2023
- Lucee 5.3+ and 6.x
- Operating systems
- Windows Server, Linux, macOS
- Web servers
- IIS, Apache HTTPD, Nginx (via connector)
- Prerequisites
- SMTP access if using email alerts (cfmail)
- Write permissions to the app’s logs directory
- Java 11/17 as required by your CF engine
How to Install
Folder Structure (recommended)
- /yourapp/
- Application.cfc
- /errors/
- /lib/
- /tests/
- /config/
If your project already has some of these folders, you can merge the contents.
Step-by-Step
-
Download and unzip
Extract the ZIP into your project root (or a temporary folder to inspect contents). -
Backup your current Application.cfc
If you already have Application.cfc, create a backup and compare before merging changes. -
Copy essential files
Move /errors, /lib, /tests, and /config into your app. If you already have an /errors directory, place the new files in a subfolder and merge intentionally. -
Merge Application.cfc
- If you don’t have Application.cfc, use the provided one and update the app name, mappings, and session settings.
- If you do, copy the onError() and onMissingTemplate() methods into your existing file and wire them to the new templates.
-
Set permissions
Ensure the ColdFusion service user can write to your logs folder (where the Logger.cfc will write). -
Configure SMTP (optional)
If you plan to use email alerts, set up the mail server in ColdFusion Administrator or configure cfmail credentials where applicable. -
Restart or reload the application
Save Application.cfc; your ColdFusion application will reload. Validate via /tests/throw.cfm.
How to Configure
Application.cfc essentials
Minimal example (script style) showing the global error hook:
component output=false {
this.name = “MyCFApp”;
this.sessionManagement = true;
function onError(exception, eventName) output=false {
// Log essential details
writeLog(file=”application”, text=”Unhandled: ” & exception.message);
// Expose exception to the error page via request scope
request.exception = exception;
// Show friendly error page (hides stack trace in production)
include "/errors/500.cfm";
abort;}
function onMissingTemplate(targetPage) output=false {
request.missingTemplate = targetPage;
include “/errors/404.cfm”;
abort;
}
}
Tip: If your engine/version supports it, you can also centralize logging through Logger.cfc included in /lib.
Email and logging options
- /config/error-handler.json (sample)
- environment: “development” or “production”
- showDetails: false (don’t show stack traces to users in production)
- email: to, from, subjectPrefix
- logging: file name, log level
- redactKeys: [“password”, “ssn”, “card”, “token”]
In your /errors/500.cfm, the template reads request.exception, formats the message, and—if enabled—sends a short HTML report with cfmail using the email-error.cfm subtemplate.
Important: Always ensure sensitive variables are redacted. The provided code filters confidential keys before logging or emailing.
Optional third‑party integration
- Sentry or similar services can be integrated by posting exception data via cfhttp or using a native provider if available.
- Add a hook in onError() or email-error.cfm to send a structured JSON payload with message, stack, tags (server/environment), and user/session identifiers (non-PII).
How to Use
Trigger test errors
- Visit /tests/throw.cfm to generate an exception deliberately.
- Request a missing URL such as /does-not-exist.cfm to trigger onMissingTemplate() and render /errors/404.cfm.
Validate outputs
- On-screen: Users see a friendly message. In development, you can toggle showDetails to true for stack traces behind an IP check or secret token.
- Logs: Confirm new entries in your chosen log file (or application.log).
- Emails: Check that alert emails are received by your dev/ops inbox.
Benefits and Use Cases
- Faster triage and fewer late-night outages
- Centralized logging, consistent message formatting, and contextual metadata make root-cause analysis faster.
- Production-safe user experience
- A friendly 500 page prevents raw stack traces and protects sensitive data by default.
- Easy consistency across teams
- Standard patterns for CFML error handling, including onError, onMissingTemplate, and cftry/cfcatch examples, reduce variance between apps.
- Smoother operations and observability
- Optional email alerts plus hooks for Sentry or log aggregation help you catch exceptions early.
- Works with both Adobe ColdFusion and Lucee
- A single approach for multiple environments simplifies deployment and maintenance.
Common scenarios:
- Migrating legacy apps that still use cferror or Application.cfm into Application.cfc-based error handling.
- Creating a global exception handler for new microservices or APIs running on ColdFusion/Lucee.
- Standardizing error logging and alerting across multiple projects and teams.
Pros:
- Quick drop-in setup
- Secure by default with redaction
- Extensible hooks for mail and third-party providers
Cons:
- You still need to configure SMTP and permissions
- Advanced setups (database logging, distributed tracing) require custom code additions
Best Practices
- Default to “safe” in production
- Keep showDetails=false and never display stack traces to end users.
- Redact aggressively
- Define redactKeys and sanitize request headers, form fields, and session variables before logging.
- Use cftry/cfcatch for known error domains
- Reserve onError() for truly unexpected exceptions; handle domain-specific failures with targeted cftry/cfcatch blocks.
- Attach correlation IDs
- Generate a request ID and include it in logs, emails, and the user-facing 500 page so support can correlate reports.
- Rate-limit alerts
- Prevent inbox flooding during error storms with simple throttling or aggregation.
- Separate dev/test/prod behaviors
- Tie configuration to environment variables or simple JSON config. Never rely solely on code comments or manual toggles.
- Test after every deployment
- Keep /tests/throw.cfm in a secured area and re-validate the pipeline post-release.
Key Takeaways
- A robust ColdFusion error handler should be global, production-safe, and easy to extend.
- The ZIP includes Application.cfc hooks, friendly error pages, logging utilities, and documentation to get you running quickly.
- Configuration via JSON and clear code examples help you tailor behavior per environment.
- Proper redaction, logging, and optional alerting drive faster resolution without exposing sensitive data.
FAQ
Can I use this with an existing Application.cfc?
Yes. Copy the onError() and onMissingTemplate() functions into your Application.cfc, then point their includes to /errors/500.cfm and /errors/404.cfm. Merge carefully to avoid overwriting your existing settings (e.g., sessions, mappings).
Does it work on both Adobe ColdFusion and Lucee?
Yes. The core approach is compatible with Adobe ColdFusion 2018/2021/2023 and Lucee 5.3+/6.x. Where minor differences exist (e.g., logging configuration), the README.pdf notes engine-specific tips.
How do I prevent sensitive data from appearing in logs or emails?
Use the redactKeys setting in /config/error-handler.json. The templates filter these keys from URL, FORM, and session scopes before logging or emailing. You can add or remove keys as needed.
Should I still use cftry/cfcatch blocks?
Absolutely. Use cftry/cfcatch to handle expected failures (e.g., validation, external API timeouts) close to where they occur. The global onError() acts as a safety net for unhandled exceptions.
Can I integrate with Sentry or other error trackers?
Yes. The template includes guidance for posting exceptions via cfhttp to services like Sentry. Add a small hook to onError() that sends message, stack trace, tags (environment/server), and a correlation ID.
