ClassCircularityError thrown by ClassLoader.defineClass

I'm loading classes using a custom class loader. For the most part, everything works, but sometimes when I load particularly complex projects/libraries, I get a strange bug:

Exception in t开发者_StackOverflow社区hread "main" java.lang.ClassCircularityError: 
  org/apache/commons/codec/binary/Hex
    at java.lang.ClassLoader.defineClass1(Native Method)
    at java.lang.ClassLoader.defineClassCond(ClassLoader.java:632)
    at java.lang.ClassLoader.defineClass(ClassLoader.java:616)
    at java.lang.ClassLoader.defineClass(ClassLoader.java:466)
    at my.custom.class.Loader.loadClass(...)

Looking at the Javadocs, I wouldn't expect defineClass to throw this particular error. org/apache/commons/codec/binary/Hex is the class I'm trying to load. It's almost as if defineClass wants a copy of the class before it'll define the class - which makes no sense to me.

Ideas?

---

A ClassCircularityError is thrown when some class is a (direct or indirect) superclass of itself, some interface (directly or indirectly) extends itself or similar.

This should normally not occur as a well-behaved compiler will not produce such classes, but using different versions of a library (or using several libraries containing different versions of a class) could bring this problem.

Scan your libraries for double class names, in particular have a look if there are multiple versions of the mentioned org.apache.commons.codec.binary.Hex class.

---

A ClassCircularityError is also thrown when an exception occurs during the definition of a class, for example when using a custom class loader.

The exception's type is misleading, but I think you can check the enclosed exception which should reflect what really happened.

(Full disclosure: I write my own class loaders.)

Here is an example:

java.lang.StackOverflowError
    at java.base/java.lang.LinkageError.<init>(LinkageError.java:55)
    at java.base/java.lang.ClassCircularityError.<init>(ClassCircularityError.java:53)

Here, the StackOverflowError thrown inside my class loader is the actual cause of the problems. No class circularities were involved. Initially I was confused by the message too.