{"record":{"id":"c92abb0a8c0221b2","repo":"hibernate/hibernate-orm","slug":"unable-to-locate-named-class-string","errorCode":null,"errorMessage":"Unable to locate named class \" + string","messagePattern":"Unable to locate named class \" \\+ string","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/ClassJavaType.java","lineNumber":54,"sourceCode":"\t\treturn true;\n\t}\n\n\t@Override\n\tpublic String toString(Class<?> value) {\n\t\treturn value.getName();\n\t}\n\n\t@Override\n\tpublic Class<?> fromString(CharSequence string) {\n\t\tif ( string == null ) {\n\t\t\treturn null;\n\t\t}\n\n\t\ttry {\n\t\t\treturn ReflectHelper.classForName( string.toString() );\n\t\t}\n\t\tcatch ( ClassNotFoundException e ) {\n\t\t\tthrow new HibernateException( \"Unable to locate named class \" + string );\n\t\t}\n\t}\n\n\t@Override\n\tpublic <X> X unwrap(Class<?> value, Class<X> type, WrapperOptions options) {\n\t\tif ( value == null ) {\n\t\t\treturn null;\n\t\t}\n\t\tif ( Class.class.isAssignableFrom( type ) ) {\n\t\t\treturn type.cast( value );\n\t\t}\n\t\tif ( String.class.isAssignableFrom( type ) ) {\n\t\t\treturn type.cast( toString( value ) );\n\t\t}\n\t\tthrow unknownUnwrap( type );\n\t}\n\n\t@Override","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/ClassJavaType.java#L36-L72","documentation":"ClassJavaType.fromString hydrates a Class-typed attribute by loading the class named in the column via ReflectHelper.classForName(). ClassNotFoundException is wrapped in HibernateException('Unable to locate named class <name>') — note the original exception is not chained, so the message is the only clue. Thrown while loading the entity row.","triggerScenarios":"Rows whose class-name column references a class missing from the runtime classpath: the class was renamed/moved during refactoring, an optional module is not deployed, or environments run different artifacts.","commonSituations":"Package refactors without updating stored class names; removal of a deprecated subtype while old rows still reference it; shaded/relocated jars in production; dev machine has the class but CI/prod does not.","solutions":["Update the stored names (UPDATE ... SET type_name = 'com.new.Fqn') or add a converter mapping legacy names to current classes.","Restore or deploy the artifact containing the missing class before loading those rows.","Quarantine offending rows with a WHERE filter until data is fixed."],"exampleFix":"-- before: class moved from com.acme.OldType to com.acme.NewType\nSELECT * FROM items; -- hydrate throws HibernateException: Unable to locate named class com.acme.OldType\n\n-- after\nUPDATE items SET type_name = 'com.acme.NewType' WHERE type_name = 'com.acme.OldType';","handlingStrategy":"try-catch","validationCode":"static boolean classResolves(String fqn) {\n    try { Class.forName(fqn, false, Thread.currentThread().getContextClassLoader()); return true; }\n    catch (ClassNotFoundException e) { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n    return session.find(Item.class, id);\n} catch (HibernateException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unable to locate named class\")) {\n        // note: the ClassNotFoundException cause is NOT chained\n        throw new DataIntegrityException(\"Stale class name in row \" + id + \": \" + e.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Treat stored class names as schema: run data migrations with package refactors.","Validate stored names against the classpath in CI for seed/reference tables.","Prefer short discriminator strings over full class names in columns."],"tags":["hibernate","class-loading","refactoring","classpath"],"backgroundTag":"class-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}