{"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":"error","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/e8729d043887bf0d0baf91e062e909b56eb2b708/spring-beans/src/main/java/org/springframework/beans/BeanUtils.java#L129-L165","documentation":"Thrown as BeanInstantiationException by instantiateClass(Class) when getDeclaredConstructor() raises a LinkageError (typically NoClassDefFoundError or UnsatisfiedLinkError) rather than NoSuchMethodException. It signals that the class's definition cannot be resolved at runtime, usually because a referenced type or resource is missing (BeanUtils.java:146-148).","triggerScenarios":"instantiateClass(Foo.class) where Foo references a type that is not on the classpath/module path, or whose static initializer fails, triggering a LinkageError during reflective constructor lookup.","commonSituations":"Missing optional dependency at runtime (class present at compile time, absent at runtime); fat-jar shading that dropped a transitive class; module path misconfiguration; a superclass/interface removed in a newer library version; failed static initializer.","solutions":["Inspect the wrapped LinkageError (cause) to find the missing class name, then add the missing dependency to the runtime classpath.","Run 'mvn dependency:tree' / 'gradle dependencies' to confirm the required artifact resolves at runtime scope.","If shading, ensure includes cover all referenced classes (fix the shade plugin filters).","Pin compatible library versions so referenced types still exist (avoid version mismatches)."],"exampleFix":"// before: Foo extends RemovedSuperClass -> NoClassDefFoundError\nBeanUtils.instantiateClass(Foo.class);\n\n// after\n// add the dependency providing RemovedSuperClass to runtime classpath\n<dependency><groupId>org.example</groupId><artifactId>core</artifactId><version>2.x</version></dependency>","handlingStrategy":"try-catch","validationCode":"// Best-effort: confirm class is loadable & has no missing references\ntry { clazz.getDeclaredConstructor(); }\ncatch (NoClassDefFoundError | LinkageError e) { /* report missing dependency before calling Spring */ }","typeGuard":"public static boolean isLinkageClean(Class<?> c) {\n  try { c.getDeclaredConstructor(); return true; }\n  catch (LinkageError | NoSuchMethodException e) { return false; }\n}","tryCatchPattern":"try { BeanUtils.instantiateClass(clazz); }\ncatch (BeanInstantiationException e) {\n  if (e.getCause() instanceof LinkageError le) {\n    // le.getMessage() names the missing class; add the dependency\n  }\n}","preventionTips":["Keep compile- and runtime-scoped dependencies consistent (mvn dependency:tree).","Verify shade/fat-jar filters include all referenced classes.","Pin compatible library versions to keep referenced types present."],"tags":["spring-beans","beanutils","instantiation","linkage-error","classpath","dependency"],"analyzedSha":"e8729d043887bf0d0baf91e062e909b56eb2b708","analyzedAt":"2026-08-04T19:07:39.725Z","schemaVersion":2}