{"record":{"id":"0c4005ef8f525a2a","repo":"hibernate/hibernate-orm","slug":"could-not-create-dynamicparameterizedtype-for-type","errorCode":null,"errorMessage":"Could not create DynamicParameterizedType for type: \" + typeName","messagePattern":"Could not create DynamicParameterizedType for type: \" \\+ typeName","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java","lineNumber":968,"sourceCode":"\t\t\t\t: directAnnotationUsages.toArray( Annotation[]::new );\n\t}\n\n\tprotected ParameterType createParameterType() {\n\t\ttry {\n\t\t\tfinal int size = columns.size();\n\t\t\tfinal var columnNames = new String[size];\n\t\t\tfinal var columnLengths = new Long[size];\n\t\t\tfor ( int i = 0; i < size; i++ ) {\n\t\t\t\tif ( columns.get(i) instanceof Column column ) {\n\t\t\t\t\tcolumnNames[i] = column.getName();\n\t\t\t\t\tcolumnLengths[i] = column.getLength();\n\t\t\t\t}\n\t\t\t}\n\t\t\t// todo : not sure this works for handling @MapKeyEnumerated\n\t\t\treturn createParameterType( columnNames, columnLengths );\n\t\t}\n\t\tcatch ( ClassLoadingException e ) {\n\t\t\tthrow new MappingException( \"Could not create DynamicParameterizedType for type: \" + typeName, e );\n\t\t}\n\t}\n\n\tprivate ParameterType createParameterType(String[] columnNames, Long[] columnLengths) {\n\t\tfinal var attribute = (MemberDetails) typeParameters.get( DynamicParameterizedType.XPROPERTY );\n\t\treturn new ParameterTypeImpl(\n\t\t\t\tclassLoaderService()\n\t\t\t\t\t\t.classForTypeName( typeParameters.getProperty( DynamicParameterizedType.RETURNED_CLASS ) ),\n\t\t\t\tattribute != null ? attribute.getType() : null,\n\t\t\t\tgetAnnotations( attribute ),\n\t\t\t\ttable.getCatalog(),\n\t\t\t\ttable.getSchema(),\n\t\t\t\ttable.getName(),\n\t\t\t\tparseBoolean( typeParameters.getProperty( DynamicParameterizedType.IS_PRIMARY_KEY ) ),\n\t\t\t\tcolumnNames,\n\t\t\t\tcolumnLengths\n\t\t);\n\t}","sourceCodeStart":950,"sourceCodeEnd":986,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java#L950-L986","documentation":"SimpleValue builds a ParameterType (DynamicParameterizedType) to hand column metadata to types like enums, @Enumerated, or custom ParameterizedType implementations. While assembling it, it must load the returned class named in the type parameters (DynamicParameterizedType.RETURNED_CLASS). When that class cannot be loaded, the ClassLoadingException is wrapped in this MappingException naming the offending typeName.","triggerScenarios":"A property using a type whose type-parameters reference a class name that is not loadable in Hibernate's class loader: @Type(MyType.class) with parameters naming a moved/renamed class, hbm.xml <type name=\"...\"><param name=\"returnedClass\">bad.Foo</param></type>, or @Enumerated where the enum class was renamed or lives in a module invisible to the ORM classloader.","commonSituations":"Refactoring that renames or moves an enum or custom BasicType without updating hbm.xml or @TypeDef parameters; fat WAR/classloader isolation in application servers where Hibernate's classloader cannot see the app class; stale compiled mappings after upgrades; copy-pasted param values with wrong package names.","solutions":["Check the exception cause (ClassLoadingException) for the exact class name that failed, and fix the name in the @TypeDef/@Type parameters or hbm.xml <param>.","If the class legitimately moved, update its package in every type parameter that references it.","In app servers, ensure the entity/enum classes are visible to the classloader Hibernate uses (package the classes with the persistence unit, not in a sibling isolated module).","After renames, do a project-wide search for the old fully-qualified name in mapping resources."],"exampleFix":"<!-- before -->\n<property name=\"status\" type=\"org.example.GenericEnumType\">\n    <param name=\"enumClass\">com.oldpkg.Status</param>\n</property>\n\n<!-- after -->\n<property name=\"status\" type=\"org.example.GenericEnumType\">\n    <param name=\"enumClass\">com.newpkg.Status</param>\n</property>","handlingStrategy":"try-catch","validationCode":"// before building mappings, verify classes referenced by type params exist\nClass<?> returned = classLoader.loadClass(\"com.newpkg.Status\");\nassert returned != null;","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = cfg.buildSessionFactory();\n} catch (MappingException e) {\n    if (e.getMessage().startsWith(\"Could not create DynamicParameterizedType\")) {\n        Throwable cause = e.getCause(); // ClassLoadingException has the exact class name\n        throw new IllegalStateException(\"Type parameter references missing class: \" + cause.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["After refactors, project-wide search for old fully-qualified class names in mapping files.","Keep entity/enum classes packaged with the persistence unit so Hibernate's classloader sees them.","Test SessionFactory creation in CI after any rename."],"tags":["hibernate","classloading","custom-type","orm-mapping","classnotfound"],"backgroundTag":"class-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}