{"record":{"id":"bc5948e417ab06d1","repo":"hibernate/hibernate-orm","slug":"class-typename-does-not-implement-s","errorCode":null,"errorMessage":"Class '\" + typeName + \"' does not implement '\" + supertype.getName() + \"'","messagePattern":"Class '\" \\+ typeName \\+ \"' does not implement '\" \\+ supertype\\.getName\\(\\) \\+ \"'","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/MappingHelper.java","lineNumber":128,"sourceCode":"\t\tfor ( var property : properties ) {\n\t\t\tif ( ( property.isUpdatable() || property.isInsertable() ) && !property.isGenericSpecialization() ) {\n\t\t\t\tproperty.getValue().checkColumnDuplication( distinctColumns, owner );\n\t\t\t}\n\t\t}\n\t}\n\n\tstatic Class<?> classForName(String typeName, BootstrapContext bootstrapContext) {\n\t\treturn bootstrapContext.getClassLoaderAccess().classForName( typeName );\n\t}\n\n\tstatic <T> Class<? extends T> classForName(Class<T> supertype, String typeName, BootstrapContext bootstrapContext) {\n\t\tfinal var clazz = classForName( typeName, bootstrapContext );\n\t\tif ( supertype.isAssignableFrom( clazz ) ) {\n\t\t\t//noinspection unchecked\n\t\t\treturn (Class<? extends T>) clazz;\n\t\t}\n\t\telse {\n\t\t\tthrow new MappingException( \"Class '\" + typeName + \"' does not implement '\" + supertype.getName() + \"'\" );\n\t\t}\n\t}\n}\n","sourceCodeStart":110,"sourceCodeEnd":132,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/MappingHelper.java#L110-L132","documentation":"MappingHelper#classForName(supertype, ...) loads a class by name and verifies it is assignable to the required Hibernate interface (UserCollectionType, UserType and similar strategy contracts). This MappingException means the named class exists and loads, but does not implement the interface demanded by the mapping position it was declared in.","triggerScenarios":"An hbm <collection-type name=\"X\"> where X does not implement UserCollectionType; a <type name=\"X\"> used where a CompositeUserType (or another contract) is required; accidentally naming the domain class or enum instead of the type implementation class.","commonSituations":"Custom types first wired into the wrong extension point; refactoring a UserType into a UserCollectionType or back; copy-paste of type declarations between mapping positions.","solutions":["Open the named class, determine which Hibernate interface the mapping position requires, and implement that interface.","Or move the declaration to the position matching the interface the class does implement.","Verify you did not reference the wrong class - e.g. the handled Java type instead of the UserType implementation."],"exampleFix":"<!-- before -->\n<collection-type name=\"com.acme.MyList\"/> <!-- MyList does not implement UserCollectionType -->\n\n<!-- after -->\npublic class MyList implements UserCollectionType { ... }\n<collection-type name=\"com.acme.MyList\"/>","handlingStrategy":"validation","validationCode":"static <T> boolean implementsContract(Class<T> contract, String className)\n        throws ClassNotFoundException {\n    return contract.isAssignableFrom(\n        Class.forName(className, false, Thread.currentThread().getContextClassLoader()));\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep one type class per extension point; never reuse a UserType as a collection type or vice versa.","Pass Class references (annotations) instead of string names so mismatches surface earlier.","Smoke-test all custom types by building Metadata at startup."],"tags":["hibernate","orm","mapping","user-type","interface","custom-type"],"backgroundTag":"missing-interface-implementation","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}