{"record":{"id":"07323d74525552ae","repo":"hibernate/hibernate-orm","slug":"the-specified-class-cannot-be-null","errorCode":null,"errorMessage":"The specified class cannot be null","messagePattern":"The specified class cannot be null","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java","lineNumber":760,"sourceCode":"\t\treturn this;\n\t}\n\n\t/**\n\t * Read a mapping as an application resource using the convention that a class\n\t * named {@code foo.bar.Foo} is mapped by a file {@code foo/bar/Foo.hbm.xml}\n\t * which can be resolved as a {@linkplain ClassLoader#getResource(String)\n\t * classpath resource}.\n\t *\n\t * @param entityClass The mapped class\n\t *\n\t * @return {@code this} for method chaining\n\t *\n\t * @throws MappingException Indicates problems locating the resource or\n\t * processing the contained mapping document.\n\t */\n\tpublic Configuration addClass(Class<?> entityClass) throws MappingException {\n\t\tif ( entityClass == null ) {\n\t\t\tthrow new IllegalArgumentException( \"The specified class cannot be null\" );\n\t\t}\n\t\treturn addResource( hbmFileName( entityClass ) );\n\t}\n\n\tprivate static String hbmFileName(Class<?> entityClass) {\n\t\treturn entityClass.getName().replace( '.', '/' )\n\t\t\t+ \".hbm.xml\";\n\t}\n\n\t/**\n\t * Read metadata from the annotations associated with this class.\n\t *\n\t * @param annotatedClass The class containing annotations\n\t *\n\t * @return {@code this} for method chaining\n\t */\n\tpublic Configuration addAnnotatedClass(Class<?> annotatedClass) {\n\t\tmetadataSources.addAnnotatedClass( annotatedClass );","sourceCodeStart":742,"sourceCodeEnd":778,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java#L742-L778","documentation":"Configuration.addClass(Class) resolves the .hbm.xml mapping file for a class as a classpath resource (class name with '.' replaced by '/' plus \".hbm.xml\"). A null class cannot name a resource, so Hibernate rejects it immediately with IllegalArgumentException. This is a fail-fast contract check on the single argument.","triggerScenarios":"cfg.addClass(var) where var is null because a Class.forName lookup failed, a map or service returned null, or refactoring left an unset variable; loops that feed possibly-null classes into Configuration.","commonSituations":"Dynamic class scanning and string-driven configuration; migration scripts; test harnesses passing placeholders or unresolved class names.","solutions":["Null-check the class before calling addClass","Fix the upstream lookup that produced null and log the class name that failed to resolve","Use addAnnotatedClass(Class) for annotation mappings, with the same null check"],"exampleFix":"// before\ncfg.addClass(resolveEntity(name)); // resolveEntity returns null on miss -> throws\n\n// after\nClass<?> entity = resolveEntity(name);\nif (entity == null) {\n    throw new IllegalStateException(\"No entity class found for name: \" + name);\n}\ncfg.addClass(entity);","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(entityClass, \"entityClass must not be null\");\ncfg.addClass(entityClass);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate dynamically looked-up classes at the boundary where the lookup happens","Fail fast with the entity name in the message so the miss is diagnosable","Prefer addAnnotatedClass with a compile-time class reference over string-driven lookup"],"tags":["hibernate","mapping","null-check","configuration"],"backgroundTag":"null-required-parameter","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}