ColdFusion on IIS: issues troubleshooting

Sometimes, ColdFusion tends to be a real troublemaker in connection with IIS. The IIS is also not helping – the error messages are not always meaningful.

The ultimate solution to various problems is to recreate the IIS-ColdFusion connector. I described this topic briefly in HTTP Status 403 – Forbidden after ColdFusion upgrade on IIS and also I mentioned it in 404 on ColdFusion CFM files while default document is still loading.

The thing is that this is not always enough. Also, there are servers or situations when you are not allowed to remove or create an IIS-ColdFusion connector. In such a case, here is my checklist of things to do.

First things first – permissions

The ColdFusion instance is running over the Tomcat server which is called from IIS as ISAPI Module (or ISAPI Filter). I know, there are many strange statements in the previous sentence. The main thing is that each element of the chain has to be able to access the directory and files where your site is located.

The easiest way to give proper permissions is to open Properties of the folder where the site is located and give all permissions to the IIS_IUSRS group. This group contains all modules called by IIS, so it should allow IIS itself, Tomcat, and ColdFusion to gain access to the files of your website. As you can see on the screenshot below, from the directory permissions I selected the Security tab, clicked on the Edit button below the Grou or user names list, and in the new window I added IIS_IUSRS as the new user with all possible privileges. Full control is not mandatory and on production servers, it is better to keep it off.

Default document

The next thing to check is the Default Document. Click on your site in IIS and find the Default Document icon on the list.

Once there, check if there are your desired default documents on the list. For ColdFusion it is good to have at least “index.cfm” and “default.cfm” there. If they are not listed, you can click “Add” on the Actions list on the right side of the screen.

Handler mappings

When IIS is loading your default document but is not able to handle it properly, it displays a 404.3 error (because it is not able to find a proper handler). It is often connected with the “Error Code: 0x80070032” which doesn’t tell us much about what happened. Here is an example error screen:

The “Error Code: 0x80070032” is caused by the missing cfc and (or) cfm handler. IIS simply doesn’t know what to do with these files. How to serve them. Let’s check if they are in place. On your website in IIS, find and click on the Handler Mappings icon:

It should contain on the list the CFM and CFC handlers:

If they are not present, we should add them. The most common way is by executing the connector creation tool, but let’s assume that we are not able to do this. I assume that you have at least one working ColdFusion website in your IIS. Without this, you have to use the connector creation tool in order to generate the first connector between IIS and ColdFusion.

As the first step here, go to your working ColdFusion website Handler Mappings, click on cfcHandler and copy the contents of the Executable field. We will use it in our manually created handler on the site that is not working. In order to do this, go back to your not working site, click on the Handler Mappings and click on the “Add Script Map” on the Actions panel:

Now you can fill the window using “*.cfc” in the Request path, the value you copied in the Executable field, and “cfcHandler” in the Name field.

Now you should click on Request Restrictions and change Mappings to “File or folder”.

When you click on the “OK” button, such a message will be displayed and you should click “Yes”:

There is a possibility that IIS will give you one more popup saying that the file is in use. Close this popup and click “OK” on the new handler again – for as long as it needs. Sometimes it can take 3-5 times to get to the handler on busy servers – the destination executable is simply used by the other IIS process.

ISAPI filter – error code 0x80004005

Once you have your handlers in place, you may see the IIS error 500 followed by the Error Code 0x80004005. Something like this:

This means that IIS was trying to call the executable, but there was an error calling it. In most cases, it is related to the missing ISAPI Filter of ColdFusion. Go to your IIS website again and click on the ISAPI Filters icon:

Normally, you should see the ColdFusion connector executable, like the one you added in Handler Mappings – something like this:

Once again, if this is missing, you should go to the site that is working on the same server, take a look at the ISAPI Filters of this site and copy the Executable. Please note that this is the same we are using in Handler Mappins, so you can use it again. In order to add the ISAPI Filter, go back to your “not working” site ISAPI Filters, click the “Add” action in the Actions menu on the right. Fill the form with the Filter name of ColdFusion and the Executable you used for your Handler Mappings:

Right now we are almost there. There is still one more step though…

Jakarta ISAPI redirect – Error code 0x80070002

The site can work for most of the cases, but from time to time you receive the Error Code 0x80070002? Something like this:

This means that there are virtual directories missing. Once again we will have to create them manually. Normally, the connector configuration tool is creating them for you, but in this case, we will create them manually. There are two of them – CFIDE and jakarta:

In order to add them manually, right-click on the Globe icon of your not working IIS website, and from the list select “Add Virtual Directory”

You will have to create each of them separately. Here are the screenshots of the filled forms. Please note one thing: you should change the ColdFusion installation path to your own! The first one is CFIDE:

The jakarta virtual directory is pointing to the connector location (take a look at your Handler Mappings and use the same directory):

Conclusion

The above are the most common steps to perform in order to fix typical ColdFusion issues on IIS. They are not covering all possibilities, but the most common ones. I know that the solutions above are not described in-depth, but I wanted this post to be short, but useful. Feel free to add your comments below.