{"record":{"id":"db1e069f976841ad","repo":"hibernate/hibernate-orm","slug":"unable-to-instantiate-configured-archivedescriptor-db1e06","errorCode":null,"errorMessage":"Unable to instantiate configured ArchiveDescriptorFactory - {}","messagePattern":"Unable to instantiate configured ArchiveDescriptorFactory - (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/jpa/boot/spi/PersistenceConfigurationDescriptor.java","lineNumber":400,"sourceCode":"\t\t\t\t\t\te\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate static ArchiveDescriptorFactory determineArchiveDescriptorFactory(\n\t\t\t@Nonnull ConfigurationService configurationService,\n\t\t\t@Nonnull ClassLoaderService classLoaderService) {\n\t\tfinal Object setting = configurationService.getSettings().get( PersistenceSettings.SCANNER_ARCHIVE_INTERPRETER );\n\t\tif ( setting instanceof ArchiveDescriptorFactory ref ) {\n\t\t\treturn ref;\n\t\t}\n\t\telse if ( setting instanceof Class<?> implClass ) {\n\t\t\ttry {\n\t\t\t\treturn (ArchiveDescriptorFactory) implClass.getDeclaredConstructor().newInstance();\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new HibernateException( \"Unable to instantiate configured ArchiveDescriptorFactory - \" + implClass.getName(), e );\n\t\t\t}\n\t\t}\n\t\telse if ( setting != null ) {\n\t\t\tvar implClassName = setting.toString();\n\t\t\tvar implClass = classLoaderService.classForName( implClassName );\n\t\t\ttry {\n\t\t\t\treturn (ArchiveDescriptorFactory) implClass.getDeclaredConstructor().newInstance();\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new HibernateException( \"Unable to instantiate configured ArchiveDescriptorFactory - \" + implClass.getName(), e );\n\t\t\t}\n\t\t}\n\t\treturn new StandardArchiveDescriptorFactory();\n\t}\n\n}\n","sourceCodeStart":382,"sourceCodeEnd":417,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/jpa/boot/spi/PersistenceConfigurationDescriptor.java#L382-L417","documentation":"Thrown by PersistenceConfigurationDescriptor.determineArchiveDescriptorFactory() as a HibernateException when the class configured via hibernate.archive.interpreter (Class-object form) cannot be instantiated. ArchiveDescriptorFactory decides how archive URLs (jars, directories, nested archives) are interpreted during scanning; a custom implementation must be constructible with a public no-arg constructor.","triggerScenarios":"Setting hibernate.archive.interpreter to a Class whose getDeclaredConstructor().newInstance() fails - missing no-arg constructor, abstract class, non-public class/constructor, or a throwing constructor - during EntityManagerFactory boot.","commonSituations":"Custom archive interpretation for exotic packaging (e.g. WAR/EAR layouts or virtual filesystems) where the implementation class was written with constructor parameters or package-private visibility.","solutions":["Give the ArchiveDescriptorFactory implementation a public no-arg constructor.","Ensure the class is public, concrete, and implements org.hibernate.boot.archive.scan.spi.ArchiveDescriptorFactory.","Check the cause for a constructor-thrown exception and defer any I/O setup to first use.","If you only need a different jar protocol handler, consider contributing via ServiceLoader instead of this setting."],"exampleFix":"// before\npublic class VfsArchiveDescriptorFactory implements ArchiveDescriptorFactory {\n    VfsArchiveDescriptorFactory(Vfs vfs) { ... } // package-private + args\n}\n\n// after\npublic class VfsArchiveDescriptorFactory implements ArchiveDescriptorFactory {\n    public VfsArchiveDescriptorFactory() { }\n    public void setVfs(Vfs vfs) { ... }\n}","handlingStrategy":"validation","validationCode":"Class<?> c = (Class<?>) settings.get(\"hibernate.archive.interpreter\");\nif (c != null) c.getDeclaredConstructor().newInstance(); // public no-arg ctor required","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Make custom ArchiveDescriptorFactory implementations public with public no-arg constructors.","Defer VFS/resource acquisition out of the constructor."],"tags":["hibernate","jpa","archive-scanning","configuration","instantiation"],"backgroundTag":"configured-class-instantiation-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}