ColdFusion 8: Handling missing CFM files

This post is more than 2 years old.

One of the more interesting new features in ColdFusion 8 is an update to the Application.cfc file. You can now add a method called: onMissingTemplate. As you can imagine, it fires off when a request comes in for a CFM file that doesn't exist.

Take a look at the basic method signature:

<cffunction name="onMissingTemplate" returnType="boolean" output="false"> <cfargument name="targetpage" type="string" required="true">


As you can see - it has a boolean return type and one argument - the name of the page that had attempted to load. Here is a simple example:

<cffunction name="onMissingTemplate" returnType="boolean" output="false"> <cfargument name="targetpage" type="string" required="true">
&lt;!--- log it ---&gt;
&lt;cflog file="missingfiles" text="#arguments.targetpage#"&gt;
&lt;cflocation url="/apptest/404.cfm?f=#urlEncodedFormat(arguments.targetpage)#" addToken="false"&gt;


In this case, I log the file to a log named missingfiles. I then send the user to a page and pass along the file she tried to load. On 404.cfm, all I do is tell the user their file didn't exist and I direct them to the home page. You could handle this anyway you like of course. For example - why not just log it and then send the user to the home page? That is acceptable as well. Although personally I like to at least be told I tried to load a file that didn't exist.

It is certainly nice to have this added to ColdFusion, but there are a few caveats you need to be aware of.

First - it is only going to fire off for CFM requests. So if you try to go to:

And foo doesn't exist, it will fire. If you try to go to:

then your web server will handle it. The same applies for missing directories. Consider this example:

This will not fire onMissingTemplate.

But you can handle a "deep" directory if the end of the request is a CFM file. This will work fine:

Another thing to watch out for is that onMissingTemplate will not run onError. Therefore - simply write your code perfectly. (Ok, that is a joke.) You can wrap your code in try/catch to be extra careful.

You also need to watch out for cases where you want to browse a directory. Maybe... What I mean by this is - according to the docs, if you don't want onMissingTemplate to fire in a folder where you want directory browsing, you have to use the new application variable: welcomeFileList. However, in my tests, this was not the case.

And now for the last note - and this is the weird one. Inside of onMissingTemplate, you do have access to all the scopes you normally would. However - onApplicationStart and onSessionStart are not fired. So you cannot rely on the scopes to exist. You have to test for them. If you use the code like I did above where I simply send the user away, then it isn't a big deal. Once the user is sent to 404.cfm, her session will be created. But it is something to keep in mind.

Raymond Camden's Picture

About Raymond Camden

Raymond is a developer advocate for HERE Technologies. He focuses on JavaScript, serverless and enterprise cat demos. If you like this article, please consider visiting my Amazon Wishlist or donating via PayPal to show your support. You can even buy me a coffee!

Lafayette, LA