I have a library that I am distributing on maven in the new version I will be changing the exceptions some methods are throwing. Is this considered a breaking change? If this is the only change in the new version, should I increment the major version (I am using SemVer 2)?

1 Answer 1


Could these exceptions break users' code if they are using your package as the documentation describes? Or are these exceptions an unadvertised or specifically annotated implementation detail?

If it's the former, that seems to be a breaking change which would require a major version change. If it's the latter, it may only need a patch or minor release. Semver says that "incompatible API changes" should lead to major releases, so it depends whether these exceptions are part of your programs API.

For example, if this new exception can bubble out to end users and they built their code around handling the old exception, that's a breaking change. If your code always catches this exception and handles it (presumably in a different way than the old exception) or it only reaches the user in new cases, this seems more like an implementation detail or new feature unless the way exceptions are handled completely changes the end result of the methods.

This answer assumes the ideal case where your documentation is clear, complete, and consistent, with implementation details explicitly annotated or covered under some general rule that you always follow. It also assumes users are aware of and treat the documentation as the API. In reality, there will likely always be cases your documentation misses or where users deviate from intended usage and in those cases, your API becomes a balance between what you think the program should do and what users have been doing with the program.

You might decide that these exceptions were clearly an implementation detail that no one should have been using and thus they only require a patch. On the other hand, without an explicit warning against it, your users' might have extensively used this exception and considered it a core feature of your program.

In this case, it comes down to knowing (and communicating with) your user base to determine how they use your code. If it really is unused, it can safely be made a patch. If these exceptions are widely used, it's tough to argue this isn't breaking user code even if doesn't follow your intended (but underspecified) API. You have to decide if you are willing to alienate some users by breaking this use case or expand the scope of your development to cover the way it's being used in practice.

  • 3
    Even if the thrown exceptions are not documented in the API doc, users may have taken a dependency on them, thus making them part of the de-facto API. If you change them, you haven't changed for formal API, but you may have broken the de-facto API, which users may or may not favorably accept.
    – Jonathan
    Commented Dec 14, 2021 at 7:52
  • 6
    I'd be careful with catering to users relying on undocumented behavior. If the exceptions aren't documented in the API, they are UB, and anybody relying on them must be prepared for surprises, including that this behavior may change in a minor version as part of some fixing or cleanup effort. Commented Dec 14, 2021 at 8:37
  • I must agree with @Hans-MartinMosner. If you rely on undocumented behavior, you are taking on the responsibility of managing change for that behavior. This undocumented behavior might be critical to you, but not the original purpose of that library. It just means the benefits of leveraging that behavior outweigh the drawbacks of unannounced breaking changes. There are legit use cases for this. Commented Dec 14, 2021 at 12:33
  • 2
    @Hans-MartinMosner I think there's a grey area of behaviour which is undocumented because the documentation is poor rather than because it's an implementation detail. You could write a library that didn't explicitly document any of its parameter or return types, but anyone using that library will have to rely on those parameter and return types, so the only way to call them "undefined behaviour" is to say that the entire library is not suitable for third-party use. An undocumented but frequently encountered exception could easily fall into this category.
    – IMSoP
    Commented Dec 14, 2021 at 13:04
  • 1
    @IMSoP I think this discussion of de-facto API's has been useful, so I tried to expand on it a bit in my answer. I agree with the point about a frequently encountered and unintentionally undocumented exception arguably being a part of the de-facto API. I would say a library that didn't document any of its parameter/return types probably isn't suitable for third-party use.
    – Tyberius
    Commented Dec 14, 2021 at 17:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.