Exception indicating implementation error

Question

Problem

I wonder what best practices are to indicate implementation errors detected at runtime.

For example, if you write the following method (in Java):

public void doSth(int i) {
    try {
        runOp(i); // an operation possibly throwing FrameworkException
    } catch (FrameworkException e) {
        throw new RuntimeException("Implementation error: FrameworkException should never be thrown at this place.", e);
    }
}

and you know that by design exception FrameworkException will never be thrown but as it is a checked exception you have to handle it. Further you want to handle it because it helps debugging if it turns out that the exception can actually be thrown in cases you haven't thought of in the design. Then you want to communicate that this exception is due to an implementation error.

Possible solution

As in the example, throw an unchecked exception (as we don't want to recover) and say it is an "Implementation error" (as we got to a state which is illegal by design).

In Java there doesn't seem to be a standard exception for this, is there in other languages?

The best solution I see is to create a class ImplementationError extends RuntimeException and throw it in situations where you have detected an illegal state which must be caused by an implementation error. This is somewhat similar to assertion statements in Java which would terminate the program if a boolean condition is not met. However, assertions cannot be used to state that an Exception should not be thrown (as far as I know) and in addition assertions have to be enabled when running the program which they are not by default.

Going a step further towards language design, it would be nice if statements or blocks could be annotated with something like @IllegalThrow FrameworkException with which the exception doesn't have to and cannot be catched anymore with a try-catch block. Then ImplementationError would automatically be thrown when the exception occurs anyway.

The above example would then look as follows

public void doSth(int i) {
    @IllegalThrow FrameworkException
    runOp(i); // an operation possibly throwing FrameworkException
}

The compiler could simply generate the try-catch block in the first example to implement this feature. Maybe in Java this is even possible with annotation processing?

Questions

• What is best practice to handle these situations? Is the suggested solution appropriate?
• Are there any arguments against the suggested annotation?

Related questions

• How should I handle exception that should never be thrown? is similar but the question is rather about whether or not to check for such illegal states. My point here is more that I do want to throw an appropriate exception (I think it is best practice to give reasons as precise as possible for a crash) and rather ask what kind of Exception should be thrown (class, parameters, ...). Further I want to look at language design, i.e. whether there are better ways to express that you don't expect an exception to be thrown.
• How to deal with checked exceptions that cannot ever be thrown (linked as duplicate of the previous question) again is a bit different because it asks about exceptions that actually cannot be thrown as opposed to exception where you declare their occurrence as illegal by design.

Both questions have interesting and helpful answers but I think this question might have different answers.

Answer 1

What is best practice to handle these situations? Is the suggested solution appropriate?

Looked up the Java documentation and it's similar to C and C++. You have assert specifically for this purpose.

14.10. The assert Statement An assertion is an assert statement containing a boolean expression. An assertion is either enabled or disabled. If the assertion is enabled, execution of the assertion causes evaluation of the boolean expression and an error is reported if the expression evaluates to false. If the assertion is disabled, execution of the assertion has no effect whatsoever.

Like C and C++, you can disable the effect of assertions so that they don't slow down your release builds if you want.

assert d >= 0 && d <= s.length(); // this should never happen!

If the assertion fails (condition is false), then the language throws an AssertionError exception which clearly indicates that it's a programming error and not due to something beyond the programmer's control (ex, a corrupt external file).

It's often very important to distinguish a programmer error from external input error, because you don't want to write some robust program that starts hiding programmer errors by trying to gracefully recover from every possible exception. With programmer errors, it's often instead desirable not to gracefully recover and instead bring the software to a screeching halt so that it can never be ignored and demands an immediate fix.

How should I handle exception that should never be thrown?

I think you can just let them propagate to the point of displaying an error message in a console or just output and shutdown whenever you catch AssertError unless you're working in a mission critical software which wants to try to resume and continue operating even in the case of a critical programmer mistake. In C and C++ it instantly brings the software to a halt giving us the line number where the assertion failed and often a way to immediately start debugging it which is actually generally the most desirable thing to do in the case of something that should never happen as a result of a programmer mistake.

How to deal with checked exceptions that cannot ever be thrown [...]

Here I have some C++ bias and I'm not sure if my suggestions are idiomatic in Java, but since the question is somewhat language agnostic, I don't think you should be catching so frequently.

A try/catch should model the concept of a user-oriented transaction (the user could be a programmer using a library in some cases) to be completed in full or rolled back as a whole in the event of a failure. It's not akin to C-style error code propagation manually down the call stack. If you try to catch every possible error that could be thrown immediately after it's thrown, and also try to catch every possible exception as specifically as possible, that defeats a lot of the purpose of exception handling. The richness of exception handling comes from minimizing the number of functions in your system that have to be concerned with handling errors and minimizing the amount of knowledge they need about the error through inheritance and polymorphism. Throwing should go all the way down the call stack to a catch site where it makes the most sense to recover and report the error from the standpoint of the user operation being performed with automated cleanup along the way as it skips past functions and goes straight to the place where exception recovery makes the most user-oriented sense.

Exception handling becomes useful when you don't have to place so many catch blocks and can catch exceptions as generally as possible, not caring so much what type of exception it is provided that you can gracefully recover from it, rolling back any side effects along the way to put the system back into a clean state as though the operation never happened and extracting whatever basic information you need to report the error to the user as necessary. That doesn't require you to litter your code trying to catch things that could never throw at every site that could throw.

For example, there could be hundreds of function calls that could fail in the process of loading a file, but a file loader shouldn't have hundreds of catch blocks trying to catch every one of them individually, otherwise it becomes just as cumbersome or more than manual error code propagation. In many cases a file loader should be able to just get away with one try/catch block for the entire file loading operation/transaction. All that matters really is whether the file loaded or couldn't load after all that's done. If it failed it's only of slight interest to know whether it failed due to a memory allocation failure, a failure to load an external resource, a corruption in the file, etc, which you can extract often just from the message attached to the exception without trying to catch every single possible type that could ever be thrown (which is impossible to foresee if the functions the file loader calls might be changed in the future by people other than you). So try to catch more generally and less frequently, and don't try to catch every single possible (and impossible) exception for every single function that could throw. Just let those functions throw past your functions to a catch site where it makes the most user-oriented sense to recover from the error and report it.

So for example if you have a call stack like:

load_file(...)->f1(..)->f2(...)->f3(...)
    ^
only place that makes user sense
to recover from errors

Then f1, f2, and f3 above probably don't need to bother trying to catch and handle any kind of exception, since they're not recovery sites. load_file is the recovery site. So for whatever library functions f1 to f3 call, I wouldn't bother trying to catch them or catch them specifically. Catch generally and infrequently at places where it makes sense. Distinguish functions which don't need to recover from and report errors to the user from ones that don't. If you follow this and catch at a coarse enough level, not granular level where you're worried about every possible exception that could be thrown with every single function call, you shouldn't have to worry about what to do in scenarios where some function can throw an exception but never with the inputs you provide. Let the file loader deal with it which catches exception types as generally as possible.

Answer 2

There are a lot of classes of error that cannot be handled in any meaningful way. Bugs in code is one. Errors in configuration is another. In fact there are innumerable ways that things could go wrong in unlikely or unexpected ways. What to do about that? By default, the answer is to have the application crash. One of the big mistakes I see in programs is trying handle unhandleable situations. This leads to applications continuing in a improper state. In my experience, this is much worse than a crash as an application in such a state can create a lot of havoc (e.g. corrupting data, causing failures in other applications) but almost never do anything good.

• So what to do about it? Fail-fast.
• In Java how can we easily do that? Throw a RuntimeException.
• Should I subclass it? Maybe? What does that buy you?

If you are going to try to have specific error handling for a certain class of error, then subclassing RuntimeException is a great solution. If you are just going to let the stacktrace go to sys.err, then why bother? just wrap in RuntimeException and move on with your life. If it ever happens, you will know that you had an unhandled error and the stacktrace will tell you exactly where it came from.