Overview of the Problem
When an Application.cfc “does not load,” the ColdFusion engine is not invoking your application component or its event handlers (for example, onApplicationStart, onRequestStart, onRequest, onSessionStart). Practically, you may see symptoms like:
- Your Global settings (this.sessionManagement, this.mappings, this.datasource) do not take effect.
- onApplicationStart or onRequestStart logs never appear.
- Session scope is undefined, even though you expect it.
- Your request renders as if no application-wide code is running, or renders a blank page if onRequest is mishandled.
This happens when ColdFusion or Lucee does not detect and execute your Application.cfc for the current request, or it compiles/runs into an error before any visible output/log is produced. It can also happen when the web server doesn’t send the request to the CFML engine at all (IIS/Apache/Nginx Configuration issue or URL rewrite misrouting).
How ColdFusion Resolves Application.cfc
What “Application.cfc not loading” means
- ColdFusion (Adobe ColdFusion or Lucee) looks for Application.cfc in the current directory of the requested CFML page and, if not found, walks up the directory tree toward the webroot.
- If found, CF instantiates it and calls its event handlers as needed. If not found by the time it reaches the webroot boundary, your request proceeds without those app-level hooks.
- If the request never reaches ColdFusion (e.g., a static file or a rewrite rule that never targets a .cfm/.cfc), Application.cfc will not run.
Resolution order and scope
- Application.cfc takes precedence over Application.cfm.
- The file must be named exactly “Application.cfc” with correct case and extension, especially on Linux/macOS (case-sensitive file systems).
- Application.cfc must be within the webroot path (or its subdirectories). Files above the webroot are not considered for Request handling.
Possible Causes
- Incorrect filename or location (case sensitivity, not in the request’s directory tree).
- The request never reaches ColdFusion (web server connector misconfiguration; URL rewrite bypassing .cfm).
- Syntax or runtime error in Application.cfc that prevents it from compiling/initializing.
- Wrong function signatures (e.g., onRequest without including arguments.targetPage).
- Conflicting or missing application name (this.name) and related caching issues.
- Per-application settings disabled in the CF Administrator, leading to “not loading” symptoms.
- Mixed usage with Application.cfm leading to confusion.
- Template/Trusted Cache or component cache serving stale bytecode.
- File permission or Sandbox Security blocks the CF engine from reading Application.cfc.
- Wrong site/document root or wrong CF instance handling the request (multi-site/instance setups).
Quick reference (Cause → Solution):
- Wrong filename/case → Rename to “Application.cfc” with correct case.
- Outside webroot or wrong directory → Move Application.cfc into webroot or the site’s directory tree.
- Request served by web server only → Fix connector or rewrite to target a .cfm; test with a .cfm directly.
- Syntax/runtime error → Check exception.log/catalina.out; start with a minimal Application.cfc to isolate.
- Bad onRequest implementation → Ensure you include arguments.targetPage.
- Per-app settings disabled → Enable in CF Admin or move settings to CF Admin temporarily.
- Caches stale → Clear template cache; disable Trusted Cache in dev; restart instance if needed.
- File permissions/sandbox → Grant read/execute to the CF service user; adjust sandbox.
- Wrong instance/site root → Verify which instance and document root serve your request.
Step-by-Step Troubleshooting Guide
1) Verify ColdFusion is handling your request
- Create a file test.cfm in the same directory as your target page:
- Load it in the browser. If you see the server/product info, CF is serving requests. If you get a Download prompt, 404, or static content, your IIS/Apache/Nginx connector or site mapping is wrong.
Tip: Explicitly request a .cfm page (e.g., /index.cfm) to bypass static index.html precedence.
2) Confirm filename, case, and location
- Ensure the file is exactly “Application.cfc” (not application.cfc, Application.CFC on Linux/macOS).
- Place it in the active site’s webroot or a parent directory of the requested .cfm.
- If you have multiple sites/roots, double-check the document root used by the virtual host or IIS website.
3) Replace with a minimal sanity-check Application.cfc
Use a bare-minimum component that logs its execution:
component output=”false” {
this.name = "MyAppSanityCheck";
this.sessionManagement = true;
function onApplicationStart() {
writeLog(file="application", text="onApplicationStart fired");
}
function onRequestStart(string targetPage) {
writeLog(file="application", text="onRequestStart fired for #arguments.targetPage#");
}
// Only include onRequest if you need a front controller. If used, include the target page.
function onRequest(string targetPage) {
writeLog(file="application", text="onRequest fired for #arguments.targetPage#");
include arguments.targetPage;
}}
- Reload your page and check the application.log for the messages. If the logs appear, the Application.cfc is loading; the issue may lie in your original code.
4) Check the logs for compile/runtime errors
- Adobe ColdFusion:
- cfusion/logs/exception.log
- cfusion/logs/application.log
- coldfusion-out.log or console logs for startup/stack traces
- Lucee:
- lucee-server/context/logs/exception.log
- catalina.out (Tomcat)
- web-context logs under WEB-INF/lucee
Look for messages like “Could not initialize component Application” or syntax errors. Fix and retest.
Example error snippet:
Error: Variable THIS is undefined in APPLICATION.CFC: line 3
At: /path/to/site/Application.cfc:3
5) Validate event handler signatures and behavior
-
-
onRequest must include the requested template:
function onRequest(string targetPage) {
include arguments.targetPage; // Without this, nothing renders.
} -
Define argument types and names correctly (string targetPage).
-
Avoid output in handlers unless intentionally designed; set component output=”false”.
-
Ensure onApplicationStart doesn’t throw or return output.
-
6) Audit URL rewrite or front-controller rules
If you use SES URLs, ensure they resolve to a .cfm that CF can handle.
-
Apache example:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.cfm [QSA,PT,L] -
IIS URL Rewrite example:
If the rewrite targets a static file or another handler, CF won’t run, and Application.cfc won’t load.
7) Confirm per-application settings and expected scopes
-
If you rely on settings like this.sessionManagement, this.mappings, or this.datasource, confirm “Per-application settings” are enabled:
- Adobe CF Admin > Server settings > Settings > Enable Per-Application Settings.
- Lucee Admin supports per-app settings by default via Application.cfc.
-
Test session:
#session.test# If session doesn’t persist, verify this.sessionManagement = true and cookies.
8) Clear caches and reload the application
-
Disable Trusted Cache in development.
-
Clear Template Cache from the Admin.
-
Restart the CF service if in doubt.
-
Force application restart:
-
Temporarily change this.name to a new value, or
-
Call applicationStop() from a secured admin-only URL:
applicationStop();
writeOutput(“Application stopped”);
-
9) Check file permissions and sandbox/Security
- Ensure the CF service user (e.g., cfuser, local service account) has read access to Application.cfc and its directory.
- In sandboxed environments, confirm the path is permitted.
10) Verify environment, site bindings, and instance mappings
- In multi-instance setups, ensure you are editing the Application.cfc used by the instance handling traffic.
- Confirm the virtual host/site points to the expected document root.
- If you have multiple ColdFusion engines (e.g., Lucee and Adobe CF) on the same machine, confirm which one is serving your request.
Examples and Reference Configurations
Minimal Application.cfc skeleton
component output=”false” {
// Application identity and settings
this.name = "MyApp";
this.applicationTimeout = createTimespan(0,2,0,0);
this.sessionManagement = true;
this.sessionTimeout = createTimespan(0,0,30,0);
this.setClientCookies = true;
// Optional: per-app mappings, datasource, etc.
// this.mappings["/lib"] = expandPath("./lib");
function onApplicationStart() {
writeLog(file="application", text="Application started");
}
function onSessionStart() {
writeLog(file="application", text="Session started for #cgi.remote_addr#");
}
function onRequestStart(string targetPage) {
writeLog(file="application", text="RequestStart: #arguments.targetPage#");
}
// Comment out if not needed
function onRequest(string targetPage) {
include arguments.targetPage;
}
function onError(any exception, string eventName) {
writeLog(file="application", text="Error in #eventName#: #exception.message#");
// Optionally show friendly page
// location url="/error.cfm" addtoken="false";
}}
Basic Health check endpoint
Create /health.cfm in the same folder:
Check logs for onRequestStart when hitting /health.cfm.
Common mistakes and How to Avoid Them
- Wrong filename/case (Application.cfc vs application.cfc): Always use “Application.cfc” with correct case on case-sensitive systems.
- Putting Application.cfc above the webroot: Keep it in the site’s root or inside the request’s directory tree.
- Implementing onRequest without including arguments.targetPage: Always include arguments.targetPage or you’ll get a blank page.
- Relying on per-app settings while they’re disabled: Enable per-app settings or configure these in the Admin temporarily.
- Confusing Application.cfm and Application.cfc: Do not rely on Application.cfm when Application.cfc is present; cfc wins.
- URL rewrite sends to static endpoints: Ensure rewrites target a .cfm (e.g., index.cfm), not static files.
- Trusted Cache causes stale code: Disable in dev; clear template cache when changing Application.cfc.
- Invisible compile errors: Check exception.log, enable robust Debugging in dev, and use writeLog inside event handlers to confirm execution.
- Expecting sessions without enabling them: Set this.sessionManagement = true and confirm cookies are allowed.
- Not testing with a direct .cfm: Bypass index.html; request /index.cfm explicitly.
Best practices / Prevention Tips
-
Keep a minimal, predictable Application.cfc with clear logging in key events (onApplicationStart, onRequestStart).
-
Version-tag your application in logs:
this.name = “MyApp_v1.2.3″;
writeLog(text=”App version: v1.2.3 started”); -
Maintain consistent file casing and placement across environments.
-
Implement a safe admin-only trigger to applicationStop() for controlled restarts.
-
Add automated health checks that hit a .cfm to verify CF is handling requests and event hooks run.
-
Treat URL rewrite rules as code; test them whenever they change.
-
In dev/stage, keep Trusted Cache off and clear caches after changes to Application.cfc.
-
Document the site’s document root, CF instance, and connector settings to avoid “wrong place” edits.
-
Use source control and CI to deploy Application.cfc consistently across servers.
-
In Lucee/ACF differences, consult the official docs for any engine-specific settings you rely on.
Key Takeaways
- If Application.cfc “does not load,” first prove that ColdFusion is actually serving the request.
- Check filename, casing, location, and that URL rewrites target a .cfm page.
- Use a minimal Application.cfc with writeLog to verify event handlers execute.
- Validate handler signatures (especially onRequest) and per-application settings.
- Clear caches, restart the application, and verify logs to isolate and fix issues quickly.
FAQ
How can I force ColdFusion to re-run onApplicationStart without restarting the server?
- Call applicationStop() from a secured admin-only page, or temporarily change this.name in Application.cfc to a new value. The next request will trigger onApplicationStart.
Why do my Session variables not exist even though I set them?
- Ensure this.sessionManagement = true in Application.cfc and that per-app settings are enabled in the Administrator. Also verify cookies are allowed and that you’re not accidentally starting a new application (e.g., changing this.name frequently).
Does Application.cfc run if I request a static file or index.html?
- No. Application.cfc is executed for requests handled by the CFML engine (.cfm/.cfc or extensions mapped to CF). Request a .cfm explicitly or ensure your rewrite rules direct requests to a .cfm front controller.
Can both Application.cfm and Application.cfc be used together?
- Application.cfc takes precedence. Application.cfm won’t run unless you manually include it. Mixing both can cause confusion; prefer a single Application.cfc with explicit event handling.
Why do my per-application mappings or datasources not work?
- Confirm that “Enable Per-Application Settings” is turned on in the CF Administrator. If it’s disabled, settings such as this.mappings and this.datasource in Application.cfc will be ignored.
