Any "war stories" on bugs from missing things in the documentation of functions you invoked?

Question

I'm looking for interesting war stories on situations where you had a bug because you missed something important in the documentation of a class you were instantiating or a function/method you were using.

For example, I recently messed up by not reading the documentation for the Java Calendar class and noticing that it counts months from 0... Very nasty surprise that I found the first time I was dealing with a date in December.

Any stories, especially in Java, would be appreciated.

(This is for my PhD research, I'm interested in other people's experiences)

Answer 1

The java.lang.String replaceAll(String regex, String replacement) method accepts regular expression replace expressions within the replacement parameter. (Backreferences etc).

If you ignore this, it works fine until there's a \ or similar in the replacement string.

I suspect this one even could be used in injection attacks.

Edit: The "War story" in this is that I spent about half a day searching for this bug. Some developer had found that he had to insert quad-escapes in a piece of HTML content that was containing inline javascript regular expressions. Half of them were being eaten by the String.replace function. When I discussed this feature with our security guy he also commented that double layers of escaping are also prone to injection problems.

Answer 2

There are lots of them. Some of them are really subtle, though.

Most people don't know that java.lang.Object.wait (with or without a timeout) may return without timing out or receiving a notification. The documentation says you should always use it in a loop. How often have you seen it in a loop. :)

Answer 3

I've had to deal with ConcurrentModificationExceptions in production code over collections that came from java.util.Collections.unmodifiableCollection instances.

Someone (I'd assume I) apparently didn't know that that does not produce a copy of a collection, but just thinly wraps one, so the underlying collection may still be modified elsewhere and break other things.

Answer 4

I'm also pretty sure that nearly everyone who's tried to learn the servlet API didn't read this:

Servlets typically run on multithreaded servers, so be aware that a servlet must handle concurrent requests and be careful to synchronize access to shared resources. Shared resources include in-memory data such as instance or class variables and external objects such as files, database connections, and network connections. See the Java Tutorial on Multithreaded Programming for more information on handling multiple threads in a Java program.

Every person's first servlet I've ever seen was written like a fire-and-forget CGI with lots of state on the servlet instance that would just fall apart really badly when two people were using the app at the same time.

Answer 5

I've been caught out by the classic Win32 API CreateFile() function (creates or opens a file or I/O device).

On failure, it returns INVALID_HANDLE_VALUE (defined as (DWORD)-1) and not NULL as you might expect. Other functions that return handles to kernel objects return NULL on failure!

Answer 6

I've forgotten the details but back in 99 or so I got bitten by a similar off by one bug in a php function that used a length rather than an index, which wasn't clear to me based on the documentation.

These days I unit test so I would likely catch my mistake... back then I was a naive novice so it went to production and resulted in a small data loss.