Choosing error codes based on a really nice #define doesn’t necessarily lead to a readable message to the user

You’re running a program, you try to perform some operation, and out comes this error message:

The device is not ready.

Huh? What device? I wasn’t doing anything with any device. What is this error message talking about?

Reverse-engineer this message. The message “The device is not ready” is the standard text description for Windows error 21: ERROR_NOT_READY.

What happened is that the program was using some internal helper object. If somebody tries to use the object before it has been properly configured, the developer needed to return an error code to indicate this. The developer went cruising through winerror.h looking for a suitable error code, and hey look, here’s one: ERROR_NOT_READY.

Awesome, let’s return that error code.

But what the developer didn’t check is how that error message looks to the user. The function that displays the error code to the user will use the Format­Message function to perform the error-code-to-message conversion. And that produces “The device is not ready”, which is nonsense.

This is also why you see error messages like “The group or resource is not in the correct state to perform the requested operation.” This is error 5023, and the symbolic name for error 5023 is ERROR_INVALID_STATE. You can see that this error was originally intended for use with DFS replication, seeing as it’s part of a block of cluster-related error codes. But they made the mistake of giving this a generic-sounding name, so people who go trolling through winerror.h looking for an error code to use, they see this nice name and say, “Yeah, we’ll use that.”

Another error with a tempting name is ERROR_GEN_FAILURE which comes out as “A device attached to the system is not functioning.” If you search the Internet for this phrase, you’ll see people getting this error message and going on wild goose chases through Device Manager trying find the malfunctioning device.

It’s a cruel joke. There is no device. It’s just somebody using an error code designed for devices, but for a problem that has nothing to do with a device.