Application.cfc is a special CFC that ColdFusion looks for automatically in the root of an application's folder (or any folder above the requested page). It has two jobs: configuring the application through settings on the this scope, and reacting to events — an application starting, a session ending, an unhandled error — through a set of specially-named methods ColdFusion calls automatically.
Learning Objectives
After completing this lesson, you'll be able to:
- Configure an application's name, session behavior, and timeouts through this-scope settings.
- Name the core lifecycle event methods and explain when each one fires.
- Write an onApplicationStart method that checks a resource before letting the application run.
- Write an onError method that logs an uncaught exception.
Configuring the Application: this-Scope Settings
| Setting | Purpose |
|---|---|
| this.name | The application's identifier — required for the Application scope to actually work |
| this.applicationTimeout | How long the Application scope persists with no requests, set with createTimeSpan() |
| this.sessionManagement | Turns session tracking on (default is off) |
| this.sessionTimeout | How long a session persists with no activity |
| this.setClientCookies | Whether ColdFusion sends CFID/CFTOKEN cookies to the browser (default true) |
| this.clientManagement | Turns client-variable storage on (covered in the Client Variables lesson) |
component {
this.name = "MyApp";
this.applicationTimeout = createTimeSpan(7, 0, 0, 0); // 7 days
this.sessionManagement = true;
this.sessionTimeout = createTimeSpan(0, 0, 30, 0); // 30 minutes
this.clientManagement = true;
this.clientStorage = "cookie";
}<cfcomponent>
<cfset this.name = "MyApp">
<cfset this.applicationTimeout = createTimeSpan(7, 0, 0, 0)>
<cfset this.sessionManagement = true>
<cfset this.sessionTimeout = createTimeSpan(0, 0, 30, 0)>
<cfset this.clientManagement = true>
<cfset this.clientStorage = "cookie">
</cfcomponent>The Lifecycle Methods, at a Glance
ColdFusion calls these methods automatically, by name, when the matching event happens — nothing has to invoke them manually.
| Method | Fires when |
|---|---|
| onApplicationStart | The very first request the application ever receives |
| onSessionStart | A new session begins (requires sessionManagement = true) |
| onRequestStart | The beginning of every single request, before the page runs |
| onRequest | Right after onRequestStart — has to explicitly include the page itself |
| onSessionEnd | A session times out from inactivity |
| onApplicationEnd | The application times out, or the server shuts down |
| onError | An uncaught exception happens anywhere in the application |
| onMissingTemplate | A request asks for a .cfm page that doesn't exist |
onApplicationStart — Checking a Resource Before the App Runs
<cfscript>
function onApplicationStart() {
try {
testDB = queryExecute("SELECT 1 AS ok", {}, {datasource: "myAppDB"});
} catch (database e) {
writeLog(file = "myapp", type = "error", text = "Database unavailable at startup");
return false; // application will not start
}
application.startedAt = now();
return true;
}
</cfscript><cffunction name="onApplicationStart" returnType="boolean">
<cftry>
<cfquery name="testDB" datasource="myAppDB">
SELECT 1 AS ok
</cfquery>
<cfcatch type="database">
<cflog file="myapp" type="error" text="Database unavailable at startup">
<cfreturn false>
</cfcatch>
</cftry>
<cfset application.startedAt = now()>
<cfreturn true>
</cffunction>Returning false (or letting an exception escape uncaught) stops the application from starting at all — ColdFusion retries onApplicationStart again on the next request.
onRequestStart vs onRequest
These two run back to back at the start of every request, but they're not interchangeable. onRequestStart is for setup work (checking authorization, initializing request-scoped data) and returns a boolean — return false to stop the request entirely. onRequest, if it's implemented at all, is responsible for actually including the requested page itself.
<cfscript>
function onRequestStart(targetPage) {
if (hour(now()) >= 1 && hour(now()) < 3) {
writeOutput("Site is down for maintenance between 1-3 AM.");
return false;
}
return true;
}
function onRequest(targetPage) {
include arguments.targetPage; // required if onRequest is implemented at all
}
</cfscript><cffunction name="onRequestStart" returnType="boolean">
<cfargument name="targetPage" type="string" required="true">
<cfif hour(now()) GTE 1 AND hour(now()) LT 3>
Site is down for maintenance between 1-3 AM.
<cfreturn false>
</cfif>
<cfreturn true>
</cffunction>
<cffunction name="onRequest" returnType="void">
<cfargument name="targetPage" type="string" required="true">
<cfinclude template="#arguments.targetPage#">
</cffunction>If Application.cfc doesn't implement onRequest at all, ColdFusion runs the requested page normally on its own — onRequest is only needed when something needs to wrap or filter every page's output.
onError — Catching Whatever Slips Through
<cfscript>
function onError(exception, eventName) {
writeLog(file = this.name, type = "error", text = "Event: " & eventName);
writeLog(file = this.name, type = "error", text = "Message: " & exception.message);
if (eventName != "onSessionEnd" && eventName != "onApplicationEnd") {
writeOutput("<h2>Something went wrong.</h2>");
}
}
</cfscript><cffunction name="onError" returnType="void">
<cfargument name="exception" required="true">
<cfargument name="eventName" type="string" required="true">
<cflog file="#this.name#" type="error" text="Event: #arguments.eventName#">
<cflog file="#this.name#" type="error" text="Message: #arguments.exception.message#">
<cfif arguments.eventName NEQ "onSessionEnd" AND arguments.eventName NEQ "onApplicationEnd">
<h2>Something went wrong.</h2>
</cfif>
</cffunction>onError overrides the ColdFusion Administrator's site-wide error handler and <cferror>, but it does not catch anything already handled by a try/catch. It also can't display output if the error happened during onApplicationEnd or onSessionEnd — there's no page to output to at that point, only logging works.
Common Beginner Mistakes
Forgetting this.name
Without a name set, the Application scope doesn't behave as a stable, isolated scope for that application — it's easy to forget since ColdFusion won't necessarily error immediately, the app just won't work as expected.
Implementing onRequest but forgetting to include the target page
Once onRequest is implemented at all, it becomes fully responsible for running the requested page — forgetting the include (or <cfinclude>) call means the page's own content never actually runs.
Expecting onError to catch everything, including try/catch'd exceptions
onError only fires for exceptions that escape uncaught all the way to the top. Anything already handled inside a try/catch block never reaches it.
Best Practices
- Always set this.name explicitly — never leave the application unnamed.
- Keep onRequestStart focused on setup/authorization checks; keep the actual page-serving logic in onRequest only when genuinely needed (output filtering, wrapping every page in shared markup).
- Log inside onError even when it can't display anything to the user — onApplicationEnd/onSessionEnd errors are otherwise invisible.
Interview Questions
What does returning false from onApplicationStart do?
It prevents the application from starting at all. ColdFusion retries onApplicationStart on the next request that comes in.
What's the practical difference between onRequestStart and onRequest?
onRequestStart runs first and is for setup/authorization checks, returning a boolean to allow or block the request. onRequest, if implemented, must explicitly include the target page itself — it fully takes over serving the page.
Why can't onError display output during onApplicationEnd or onSessionEnd?
Those two events aren't tied to an active user request, so there's no page context to output to — onError can still log the error, just not display it.
Summary
In this lesson, you configured an application through this-scope settings, and covered the core lifecycle event methods — onApplicationStart, onRequestStart/onRequest, onError, and how they fit into a request's flow.
What's Next?
The next lesson covers the full application lifecycle in more depth — the exact order every event fires in, from the very first request through to application shutdown.