{"record":{"id":"1ec6e1415ab0dd4d","repo":"spring-projects/spring-framework","slug":"unresolvable-class-definition","errorCode":null,"errorMessage":"Unresolvable class definition","messagePattern":"Unresolvable class definition","errorType":"exception","errorClass":"BeanInstantiationException","httpStatus":null,"severity":"critical","filePath":"spring-beans/src/main/java/org/springframework/beans/BeanUtils.java","lineNumber":147,"sourceCode":"\t * @see Constructor#newInstance\n\t */\n\tpublic static <T> T instantiateClass(Class<T> clazz) throws BeanInstantiationException {\n\t\tAssert.notNull(clazz, \"Class must not be null\");\n\t\tif (clazz.isInterface()) {\n\t\t\tthrow new BeanInstantiationException(clazz, \"Specified class is an interface\");\n\t\t}\n\t\tConstructor<T> ctor;\n\t\ttry {\n\t\t\tctor = clazz.getDeclaredConstructor();\n\t\t}\n\t\tcatch (NoSuchMethodException ex) {\n\t\t\tctor = findPrimaryConstructor(clazz);\n\t\t\tif (ctor == null) {\n\t\t\t\tthrow new BeanInstantiationException(clazz, \"No default constructor found\", ex);\n\t\t\t}\n\t\t}\n\t\tcatch (LinkageError err) {\n\t\t\tthrow new BeanInstantiationException(clazz, \"Unresolvable class definition\", err);\n\t\t}\n\t\treturn instantiateClass(ctor);\n\t}\n\n\t/**\n\t * Instantiate a class using its no-arg constructor and return the new instance\n\t * as the specified assignable type.\n\t * <p>Useful in cases where the type of the class to instantiate (clazz) is not\n\t * available, but the type desired (assignableTo) is known.\n\t * <p>Note that this method tries to set the constructor accessible if given a\n\t * non-accessible (that is, non-public) constructor.\n\t * @param clazz class to instantiate\n\t * @param assignableTo type that clazz must be assignableTo\n\t * @return the new instance\n\t * @throws BeanInstantiationException if the bean cannot be instantiated\n\t * @see Constructor#newInstance\n\t */\n\t@SuppressWarnings(\"unchecked\")","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/spring-projects/spring-framework/blob/69bf83ad716d0cfc4b0520a19b4d8b24c79d1538/spring-beans/src/main/java/org/springframework/beans/BeanUtils.java#L129-L165","documentation":"Thrown as BeanInstantiationException by instantiateClass(Class) at BeanUtils.java:147 when getDeclaredConstructor() raises a LinkageError (e.g. NoClassDefFoundError, UnsatisfiedLinkError, IncompatibleClassChangeError). This signals a class-resolution/classloader problem rather than a missing constructor: the class was loaded but its dependencies could not be resolved.","triggerScenarios":"Instantiating a class that references, in its constructor signature or field types, another class missing from the runtime classpath/module graph; a stale compiled class referencing a removed dependency; split-package or classloader-visibility issues in an app server/OSGi/JPMS environment; a native library unsatisfied at load time.","commonSituations":"Missing optional dependency JAR at runtime; version skew where a class was compiled against a newer API; fat-jar shading that dropped a transitive class; modular runtime (jlink) missing 'requires'; deployed WAR missing a lib; upgrade/downgrade of Spring or another lib leaving dangling references.","solutions":["Read the LinkageError cause (often NoClassDefFoundError) to identify the missing class.","Add the missing dependency JAR to the runtime classpath (it may be present at compile time only).","Resolve version mismatches by aligning the dependency versions across modules.","Check classloader/JPMS 'requires' and 'opens' visibility; rebuild the affected module."],"exampleFix":"// before: ctor references com.library.Config which is not on runtime classpath\nBeanUtils.instantiateClass(MyService.class); // NoClassDefFoundError wrapped\n\n// after: ensure dependency present at runtime (gradle)\n// dependencies { runtimeOnly 'com.library:library-config:1.2.0' }","handlingStrategy":"validation","validationCode":"// Sanity-check the class is resolvable with its references\ntry {\n    clazz.getDeclaredConstructor();\n} catch (LinkageError | NoClassDefFoundError e) {\n    // do not attempt instantiation; fix classpath first\n}","typeGuard":"static boolean linkageClean(Class<?> c) {\n    try { c.getDeclaredConstructor(); return true; }\n    catch (LinkageError | NoSuchMethodException e) { return false; }\n}","tryCatchPattern":"try {\n    BeanUtils.instantiateClass(clazz);\n} catch (BeanInstantiationException ex) {\n    if (ex.getCause() instanceof LinkageError link) {\n        // missing dependency/classloader issue; surface the missing class\n        throw new IllegalStateException(\"missing runtime class: \" + link.getMessage(), link);\n    }\n    throw ex;\n}","preventionTips":["Keep compile-time and runtime dependency sets aligned; verify with a dependency:tree.","Test bean instantiation in an integration environment matching production classloaders.","Use JPMS 'requires' that cover all transitive references.","After upgrades, run a smoke test that instantiates key beans to catch dangling references."],"tags":["spring-beans","beanutils","instantiation","linkage-error","classpath","classloader"],"backgroundTag":null,"analyzedSha":"69bf83ad716d0cfc4b0520a19b4d8b24c79d1538","analyzedAt":"2026-08-09T15:32:58.770Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}