{"record":{"id":"2914529e9bde02f9","repo":"hibernate/hibernate-orm","slug":"could-not-resolve-named-type","errorCode":null,"errorMessage":"Could not resolve named type: {}","messagePattern":"Could not resolve named type: (.+?)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/BasicValue.java","lineNumber":939,"sourceCode":"\t\t\t\tfinal var implicitDefinition =\n\t\t\t\t\t\tnew TypeDefinition( name, typeNamedClass, null, null );\n\t\t\t\tcontext.getTypeDefinitionRegistry().register( implicitDefinition );\n\t\t\t\treturn implicitDefinition.resolve(\n\t\t\t\t\t\tlocalTypeParams,\n\t\t\t\t\t\tgetMutabilityPlan( explicitMutabilityPlanAccess, typeConfiguration ),\n\t\t\t\t\t\tcontext,\n\t\t\t\t\t\tstdIndicators\n\t\t\t\t);\n\t\t\t}\n\n\t\t\treturn TypeDefinition.createLocalResolution( name, typeNamedClass, localTypeParams, context );\n\t\t}\n\t\tcatch (ClassLoadingException e) {\n\t\t\t// allow the exception below to trigger\n\t\t\tCORE_LOGGER.couldNotResolveTypeName( name, e );\n\t\t}\n\n\t\tthrow new MappingException( \"Could not resolve named type: \" + name );\n\t}\n\n\tprivate static <J> NamedBasicTypeResolution<J> getNamedBasicTypeResolution(\n\t\t\tFunction<TypeConfiguration, MutabilityPlan<?>> explicitMutabilityPlanAccess,\n\t\t\tConverterDescriptor<?,?> converterDescriptor,\n\t\t\tJpaAttributeConverterCreationContext converterCreationContext,\n\t\t\tBasicType<J> basicTypeByName,\n\t\t\tTypeConfiguration typeConfiguration) {\n\t\tfinal BasicValueConverter<J,?> valueConverter;\n\t\tfinal JavaType<J> domainJtd;\n\t\tif ( converterDescriptor != null ) {\n\t\t\t//noinspection unchecked\n\t\t\tvalueConverter =\n\t\t\t\t\t(BasicValueConverter<J,?>)\n\t\t\t\t\t\t\tconverterDescriptor.createJpaAttributeConverter( converterCreationContext );\n\t\t\tdomainJtd = valueConverter.getDomainJavaType();\n\t\t}\n\t\telse {","sourceCodeStart":921,"sourceCodeEnd":957,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/BasicValue.java#L921-L957","documentation":"BasicValue resolution of a named type (@Type(\"name\"), hbm type attribute, or TypeDefinition name) failed to load the class: the ClassLoadingException is logged and the failure rethrown as this MappingException naming the unresolved type.","triggerScenarios":"@Type(\"com.acme.PhoneUserType\") with a typo or missing dependency; @TypeDef target class in a jar absent at runtime; hbm <type name=\"...\"> referencing a class not on the classpath; JPMS/OSGi module not exporting the type's package.","commonSituations":"Shaded or trimmed runtime artifacts dropping optional dependencies; refactoring moves the custom type class; provided-scoped dependency needed at runtime; class visibility issues in modular runtimes.","solutions":["Fix the fully-qualified name in @Type/@TypeDef.","Ensure the jar containing the type is on the runtime classpath (inspect the deployed artifact).","Prefer class literals (@Type(MyType.class), @TypeDef(typeClass = ...)) so the compiler validates references."],"exampleFix":"// before\n@Type(\"com.acme.PhneUserType\") // typo\nprivate Phone phone;\n\n// after\n@Type(PhoneUserType.class)\nprivate Phone phone;","handlingStrategy":"validation","validationCode":"Class<?> t = Class.forName( \"com.acme.PhoneUserType\", false, getClass().getClassLoader() );\n// run for every string-named custom type before building the SessionFactory","typeGuard":null,"tryCatchPattern":"try {\n    SessionFactory sf = configuration.buildSessionFactory();\n}\ncatch ( MappingException e ) {\n    // message: Could not resolve named type: <name>\n    // fix the FQCN or add the missing jar to the runtime classpath\n}","preventionTips":["Reference custom types by class literal instead of strings","Bootstrap-assert that every @Type class loads","Verify type-providing modules are in the runtime packaging profile"],"tags":["hibernate","custom-type","classpath","classloading"],"backgroundTag":"class-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}