{"record":{"id":"533bf20b6a3d3afd","repo":"oracle/graal","slug":"class-circularity-detected","errorCode":null,"errorMessage":"Class circularity detected","messagePattern":"Class circularity detected","errorType":"exception","errorClass":"EspressoClassLoadingException.ClassCircularityError","httpStatus":null,"severity":"error","filePath":"espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/impl/EspressoClassLoadingException.java","lineNumber":42,"sourceCode":"\nimport com.oracle.truffle.api.CompilerDirectives;\nimport com.oracle.truffle.espresso.classfile.descriptors.Symbol;\nimport com.oracle.truffle.espresso.classfile.descriptors.Type;\nimport com.oracle.truffle.espresso.classfile.descriptors.TypeSymbols;\nimport com.oracle.truffle.espresso.meta.Meta;\nimport com.oracle.truffle.espresso.runtime.EspressoException;\nimport com.oracle.truffle.espresso.runtime.staticobject.StaticObject;\n\n/**\n * Indicates an exception that occurred during class loading.\n */\npublic abstract class EspressoClassLoadingException extends Exception {\n\n    private static final long serialVersionUID = 1598679948708713831L;\n\n    public static EspressoClassLoadingException.ClassCircularityError classCircularityError() throws EspressoClassLoadingException.ClassCircularityError {\n        CompilerDirectives.transferToInterpreter();\n        throw new EspressoClassLoadingException.ClassCircularityError(\"Class circularity detected\");\n    }\n\n    public static EspressoClassLoadingException.IncompatibleClassChangeError incompatibleClassChangeError(String msg) throws EspressoClassLoadingException.IncompatibleClassChangeError {\n        CompilerDirectives.transferToInterpreter();\n        throw new EspressoClassLoadingException.IncompatibleClassChangeError(msg);\n    }\n\n    public static EspressoClassLoadingException.SecurityException securityException(String msg) throws EspressoClassLoadingException.SecurityException {\n        CompilerDirectives.transferToInterpreter();\n        throw new EspressoClassLoadingException.SecurityException(msg);\n    }\n\n    public static EspressoClassLoadingException.LinkageError linkageError(String msg) throws EspressoClassLoadingException.LinkageError {\n        CompilerDirectives.transferToInterpreter();\n        throw new EspressoClassLoadingException.LinkageError(msg);\n    }\n\n    public static EspressoClassLoadingException.IllegalAccessError illegalAccessError(String msg) throws EspressoClassLoadingException.IllegalAccessError {","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/espresso/src/com.oracle.truffle.espresso/src/com/oracle/truffle/espresso/impl/EspressoClassLoadingException.java#L24-L60","documentation":"EspressoClassLoadingException.ClassCircularityError is thrown (with fixed message 'Class circularity detected') when class initialization or loading detects that a class is (transitively) its own superclass/superinterface, or a loading loop among classes. It mirrors the JVM's ClassCircularityError and is later converted to the guest error of the same name.","triggerScenarios":"A guest class hierarchy where A extends B and B extends A, a class listed as its own superinterface, or initialization cycles detected during Espresso's load/resolve of the chain. Espresso invokes this factory from its class-loading state machine when the circularity invariant trips.","commonSituations":"Bytecode generators or hot-reload tools producing cyclic hierarchies; obfuscated or hand-crafted class files with self-referential super_class indices; bugs in Espresso's lazy loading order when loading heavily-interdependent classes in parallel.","solutions":["Dump the class hierarchy of the involved classes (javap -v shows super/interfaces) and break the cycle.","If classes were generated or transformed by your tooling, regenerate with consistent hierarchy metadata.","If the input classes load fine on a standard JVM, file a GraalVM/Espresso issue with the reproducing jars.","Retry with parallel class loading disabled / single-threaded context to rule out a race in the loading state machine."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    meta.loadKlass(type, definingLoader, StaticObject.NULL);\n} catch (EspressoClassLoadingException.ClassCircularityError e) {\n    // surface which class closed the cycle; the class set must be fixed, retrying will not help\n}","preventionTips":["Validate generated hierarchies are acyclic before loading.","Do not hand-edit super_class / interfaces indices in class files.","If classes load fine on a reference JVM, report the Espresso discrepancy with the jars."],"tags":["class-loading","circularity","linkage","espresso"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}