Skip to main content
Ben Nadel at CFinNC 2009 (Raleigh, North Carolina) with: Scott Pinkston
Ben Nadel at CFinNC 2009 (Raleigh, North Carolina) with: Scott Pinkston ( @spinkston )

CFFile Upload - The Filename, Directory Name, Or Volume Label Syntax Is Incorrect

By on

In all the years that I've been using ColdFusion, I've never really had a problem with CFFile Upload (ie. CFFile action=upload). It just works; and it's awesome. The other day, however, I started getting this really odd error from my ColdFusion CFFile tag:

The filename, directory name, or volume label syntax is incorrect.

Since nothing around this code had changed recently, I knew the upload directory existed. And, when I tried to duplicate the behavior on my local machine, it always worked. I felt stumped.

Then, I realized something: My local machine and my server are running on two different operating systems. I run locally on Mac OSX; and the server runs on Windows 2008. Two different file systems, two different sets of file system restrictions.

The Mac OS is very flexible when it comes to filenames. Almost anything will be allowed. Windows, on the other hand, is much more restrictive; it has a sizable set of characters that can't be used in filenames, such as (but not limited to):

< > : " / \ | ? *

The ColdFusion CFFile syntax error that I had was being caused by a user on a Mac uploading a Windows-invalid file to the Windows server. When the CFFile tag went to write the file to disk, it was trying to use the client filename. And, rather than intelligently renaming it, the CFFile tag was simply raising an exception.

To get around this problem, I changed my CFFile Upload tag to use an explicit filename. Typically, when I use CFFile Upload, I provide a destination directory. And, when you do this, ColdFusion attempts to use the filename provided by the client. If you provide an explicit filename, however, ColdFusion will try to use that instead.

NOTE: I could have totally sworn that this latter behavior (supplying an explicit filename) was deprecated in ColdFusion 7 or thereabouts. And, while I cannot find this sentiment in any of the documentation, I will point out that all instances of the ColdFusion documentation refer to a "destination directory" and never to a destination filename.

	When saving the file, don't let ColdFusion try to use the
	client filename as the server-side filename (since this can
	cause syntax errors). Instead, give it an explicitly safe name.

	NOTE: NameConflict=MakeUnique will still work with this approach,
	even if we are explicitly defining a name.
	destination="#expandPath( './uploads/' )#"

<!--- Output the resultant meta data. --->
	label="Upload Meta Data"
	output="#expandPath( './log.txt' )#"

Notice that I am explicitly telling ColdFusion to use the filename, "". Also notice that the NameConflict attribute still works when you use an explicit filename, as demonstrated in this CFDump output:

Upload Meta Data - struct

CLIENTFILE: contacts.txt
DATELASTACCESSED: {d '2013-03-22'}
TIMECREATED: {ts '2013-03-22 09:04:34'}
TIMELASTMODIFIED: {ts '2013-03-22 09:04:34'}

Notice that ColdFusion attempted to use "", but ended up having to use, "" due to name collisions. Furthermore, the ColdFusion CFFile meta data still gives us access to the client filename, "contacts.txt", even when we tell ColdFusion to use the filename "" when attempting to save the file.

I'm not sure how I feel about using an explicit filename; perhaps that unease is due to years of not using it. Perhaps it's due to a belief that this behavior was deprecated. And, perhaps it's time to change my attitude and start using this approach; in addition to getting around this ColdFusion syntax error, supplying an explicit filename has obvious security benefits.

Want to use code from this post? Check out the license.

Reader Comments


You know, I knew the CF would allow you to specify the filename, but I didn't tend to let it do that because I wanted to be able to handle different extensions (whether I was uploading an image or some sort of document). I would write logic to make sure that the filename I ended up with had the correct extension.

When it came to uploading files, I tended to run into a different problem: some users would use a full-fledged description as the filename and the field in the database was limited to 255 characters. (Yes, they were using filenames that were longer than that!)

I got to the point where I would define my own filename and the user would only be aware of what the filename had become if they cared to pay attention to the HREF.



Yeah, the size of filenames can be shocking. I'm not the most super organized person; but sometimes, I see people with filenames that make me think, "that's the craziest thing I've ever seen. How do you find anything!"


Java instructors in college may be partly at fault for the long filenames and getting their students in the habit of using long names. I remember my Java instructors encouraging us to use extremely long names and not abbreviate at all. They told us the filenames should be descriptive and abbreviations weren't allowed at all.

I believe in love. I believe in compassion. I believe in human rights. I believe that we can afford to give more of these gifts to the world around us because it costs us nothing to be decent and kind and understanding. And, I want you to know that when you land on this site, you are accepted for who you are, no matter how you identify, what truths you live, or whatever kind of goofy shit makes you feel alive! Rock on with your bad self!
Ben Nadel