Apache Commons logo Commons FileUpload


Why is parseRequest() returning no items?
This most commonly happens when the request has already been parsed, or processed in some other way. Since the input stream has aleady been consumed by that earlier process, it is no longer available for parsing by Commons FileUpload.


Why am I getting "Read timed out" exceptions while parsing?
The most common cause of these exceptions is when FileUpload is being used on a site that is using the Tomcat ISAPI redirector. There was a bug in earlier versions of that component that caused problems with multipart requests. The bug was fixed some time ago, so you probably just need to pick up a newer version. See the Tomcat bug report for full details.


Why is NoClassDefFoundError being thrown?

There are two common causes for this error.

Firstly, it might simply mean that you do not have the Commons IO jar in your classpath. FileUpload depends on IO (see dependencies) - you can tell if this is the case if the missing class is within the org.apache.commons.io package.

Secondly this happens when attempting to rely on a shared copy of the Commons FileUpload jar file provided by your web container. The solution is to include the FileUpload jar file as part of your own web application, instead of relying on the container. The same may hold for FileUpload's IO dependency.


Why does FileItem.getName() return the whole path, and not just the file name?
Internet Explorer provides the entire path to the uploaded file and not just the base file name. Since FileUpload provides exactly what was supplied by the client (browser), you may want to remove this path information in your application. You can do that using the following method from Commons IO (which you already have, since it is used by FileUpload).
    String fileName = item.getName();
    if (fileName != null) {
        filename = FilenameUtils.getName(filename);


FileUpload and Struts 1

I'm using FileUpload in an Action, but it's not working. Why?
Struts 1 recognises multipart requests, and parses them automatically, presenting the request parameters to your code in the same manner as if they were regular request parameters. Since Struts has already processed the request, and made it available in your form bean, the input stream is no longer available for parsing, so attempting to do so with FileUpload will fail.


But I need to parse the request myself. How can I do that?
Struts 1 parses multipart a request as a part of the process of populating your form bean from that request. If, for some reason, you need to have full control over the multipart parsing, you can do so by configuring your action mapping without an associated form bean. (A better way of doing this, however, is to replace the default multipart handler with your own. See the Struts 1 documentation for details.)


FileUpload and Flash

I'm using FileUpload to receive an upload from flash, but FileUpload will always throw an Exception "Stream ended unexpectedly". What can I do?

At least as of version 8, Flash contains a known bug: The multipart stream it produces is broken, because the final boundary doesn't contain the suffix "--", which ought to indicate, that no more items are following. Consequently, FileUpload waits for the next item (which it doesn't get) and throws an exception.

The problems details and a possible workaround are outlined in Bug 143 . The workaround suggests to use the streaming API and catch the exception. The resulting code could look like this:

final List<FileItem> items = new ArrayList<FileItem>();

HttpServletRequest servletRequest = [...];
RequestContext ctx = new ServletRequestContext(servletRequest);

FileItemFactory fileItemFactory = new DiskFileItemFactory();

ServletFileUpload upload = new ServletFileUpload();
FileItemIterator iter = upload.getItemIterator(ctx);
try {
    while (iter.hasNext()) {
        FileItemStream item = iter.next();
        FileItem fileItem = fileItemFactory.createItem(item.getFieldName(),
        Streams.copy(item.openStream(), fileItem.getOutputStream(), true);
} catch (MalformedStreamException e) {
    // Ignore this


FileUpload and Flash

I have read, that there is a security problem in Commons FileUpload, because there is a class called DiskFileItem, which can be used for malicious attacks.

It is true, that this class exists, and can be serialized/deserialized in FileUpload versions, up to, and including 1.3.2. It is also true, that a malicious attacker can abuse this possibility to create abitraryly located files (assuming the required permissions) with arbitrary contents, if he gets the opportunity to provide specially crafted data, which is being deserialized by a Java application, which has either of the above versions of Commons FileUpload in the classpath, and which puts no limitations on the classes being deserialized.

That being said, we (the Apache Commons team) hold the view, that the actual problem is not the DiskFileItem class, but the "if" in the previous sentence. A Java application should carefully consider, which classes can be deserialized. A typical approach would be, for example, to provide a blacklist, or whitelist of packages, and/or classes, which may, or may not be deserialized.

On the other hand, we acknowledge, that the likelyhood of application container vendors taking such a simple security measure is extremely low. So, in order to support the Commons Fileupload users, we have decided to choose a different approach:

Beginning with 1.3.3, the class DiskFileItem is still implementing the interface java.io.Serializable. In other words, it still declares itself as serializable, and deserializable to the JVM. In practice, however, an attempt to deserialize an instance of DiskFileItem will trigger an Exception. In the unlikely case, that your application depends on the deserialization of DiskFileItems, you can revert to the previous behaviour by setting the system property "org.apache.commons.fileupload.disk.DiskFileItem.serializable" to "true".