There's nothing worse than spending a day tracking down a bug, only to discover that the bug you stumbled across is commonly known, well understood, and often easily avoidable. In the interest of saving you time, here are several known bugs that all servlet programmers should be familiar with. They're culled from my email inbox, based on the most frequently reported problems sent to me by users.

If you know of any other frequently reported bugs (FRBs) that belong on this list, write to bugs-idea at servlets dot com.

Bug: File upload doesn't always work with Apache Struts.

Symptoms: Uploads from within Struts may cause a "no leading boundary" exception

Reason: There seems to be a bug in Struts which causes it to read POST data even when it shouldn't, leaving no post data for the MultipartRequest or MultipartParser classes to read.

Bug: URLConnection.getInputStream() doesn't return until a complete response arrives under JDK 1.3.

Symptoms: The com.oreilly.servlet.HttpMessage library and other client-server applications will not get access to a server's response until the server closes the socket, when running under JDK 1.3.

Reason: There's a bug in the JDK's implementation of chunked encoding handling, see #4333920.

Bug: File upload does not work with with IBM WebSphere 4.x.

Symptoms: When handling a file upload the com.oreilly.servlet.MultipartRequest class throws an IOException that says "unexpected end of part".

Reason: There's a bug in IBM WebSphere 4.0.

Bug: File upload does not work with with Apache/Tomcat 4.0 using the mod_webapp connector

Symptoms: When handling a file upload, binary files sometimes appear truncated or corrupt.

Reason: A bug exists in the mod_webapp connector. More information is available at http://nagoya.apache.org/bugzilla/show_bug.cgi?id=3534.

Bug: File upload does not work with with Apache/Tomcat 3.2 using the ajp13 connector

Symptoms: When handling a file upload the com.oreilly.servlet.MultipartRequest class throws an IOException that says "Corrupt form data: premature ending" or sometimes "unexpected end of part".

Reason: Quoted from Lucian Cionca on tomcat-dev: "The reason for this is a bug in the doRead() method of Ajp13ConnectorRequest, which causes the doRead(byte[] b, int off, int len) in that same class to prematurely end processing . The bug is in the conversion of the value read from the bodyBuff byte-array, to an integer result. Bytes can have values from -128 to 127, while the result is expected to be a positive integer (in the range 0 to 255). A result of -1 is interpreted in the doRead(byte[] b, int off, int len) method as an error/end of input. The patch to Tomcat sources is very simple. In function "int doRead()" in Ajp13ConnectorRequest.java instead of the line
return bodyBuff[pos++];
the line
return bodyBuff[pos++] & 0xFF;
should be used. Credit for the solution should go to Amir Nuri who indicated the solution to me."

Bug: req.getDateHeader() can fail under load with Tomcat 3.2.3 and earlier

Symptoms: The method throws a StringIndexOutOfBoundsException that says, "String index out of range: 29".

Reason: Quoted from Chris Yearsley on tomcat-dev: "There is a known problem with SimpleDateFormat in that it's not threadsafe. Under load you can get unexpected exceptions, or (worse) dates being silently mangled (someone reported his dates kept being converted to the Epoch). Have a look at http://developer.java.sun.com/developer/bugParade/bugs/4228335.html".

Workaround: This looks to have been fixed recently! See the Tomcat bug report at http://nagoya.apache.org/bugzilla/show_bug.cgi?id=3546. I suspect Tomcat versions after 3.2.3 will have the fix.

Bug: Microsoft Internet Explorer often ignores the Content-Type header

Symptoms: Sending HTML or image content to IE clients results in the browser rendering the content no matter what the content type.

Reason: Internet Explorer "sniffs" the content it receives and if it appears to be of a type it recognizes (HTML, GIF, JPEG, PNG, etc) it renders the content and ignores the content type. This makes it extremely difficult to present a "download" link for an image (because a type like application/octet-stream is ignored) or to show source to a file that has HTML-style tags (because text/plain is ignored).

Workaround: For a file download, instruct the user to right-click the download link and select "Save Target As...". For presenting HTML as text, instruct the user to "View Source" the page after it's rendered.

Bug: File upload does not work with Apache JServ when uploading large binary files

Symptoms: When handling a file upload the com.oreilly.servlet.MultipartRequest class throws an ArrayIndexOutOfBoundsException.

Reason: JServ supports the older Servlet API 2.0 and in the API 2.0 source code for javax.servlet.ServletInputStream there's a bug in the readLine(byte[] buf, int off, int len) method where the len parameter is ignored, and as a result reading input lines that exceed the buf length will throw an ArrayIndexOutOfBoundsException.

Workaround: The com.oreilly.servlet library has implemented its own buffering to work around this issue. If you're using another library, upgrade to a server that supports Servlet API 2.1 or later.

Bug: Server push does not work with Microsoft Internet Explorer or Netscape Navigator 6

Symptoms: When sending multipart/x-mixed-replace responses (commonly known as server push) the client browser should display each part as its own page, but instead IE displays the whole response as one page while NN6 crashes while receiving the response.

Reason: IE has never opted to support server push. NN6 just has a nasty bug.

Workaround: Use a Refresh header or meta tag to implement client pull.

Bug: Many app server vendors still ship with Tomcat 3.1 and its buggy Jasper (JSP) implementation.

Symptoms: As Craig McClanahan write me, "One 'family'of bugs you might want to include pertains to app servers that still use the Jasper engine from Tomcat 3.1 in their current production versions (such as IBM's WebSphere 3.5.3 and earlier). Such servers inherit a large number of bugs from that Jasper code -- one that bites many users is the fact that this Jasper does not let you use pageContext.removeAttribute() to remove an attribute from request scope."

Reason: Tomcat 3.1 did not have a fully finished JSP implementation, but many app server vendors included it and still ship with it.

Workaround: Encourage your server vendor to use a newer Tomcat, and if necessary switch server vendors. Note you can find old and new Tomcat bugs listed at http://nagoya.apache.org/bugzilla/query.cgi and in the old Tomcat release notes.