{"record":{"id":"ec05d2f4a014b661","repo":"hibernate/hibernate-orm","slug":"unable-to-instantiate-configured-archivedescriptor","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/boot/scan/internal/ScanningHelper.java","lineNumber":198,"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\tprivate ScanningHelper() {\n\t}\n}","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/scan/internal/ScanningHelper.java#L180-L216","documentation":"Hibernate resolves the configured ArchiveDescriptorFactory (PersistenceSettings.SCANNER_ARCHIVE_INTERPRETER, 'hibernate.archive.interpreter') that interprets archive URLs during scanning. When the setting is a Class, determineArchiveDescriptorFactory reflectively instantiates it via getDeclaredConstructor().newInstance(); failure (no accessible no-arg constructor, abstract class, throwing constructor, or non-ArchiveDescriptorFactory type causing a ClassCastException) raises this HibernateException with the cause attached.","triggerScenarios":"Setting 'hibernate.archive.interpreter' to a Class object implementing archive interpretation (e.g. custom jar/ear layout handling) that cannot be reflectively instantiated with a declared no-arg constructor or does not implement ArchiveDescriptorFactory.","commonSituations":"Custom archive interpreter for exotic packaging (e.g. nested jars in an app-server) whose constructor requires arguments; interpreter failing in its constructor on unavailable resources; providing a Class<ArchiveDescriptor> (the per-archive type) instead of the factory type by mistake.","solutions":["Add a public no-arg constructor to the ArchiveDescriptorFactory implementation.","Pass an instance instead of a Class - the 'setting instanceof ArchiveDescriptorFactory' branch uses it directly.","Check the cause: ClassCastException usually means you supplied an ArchiveDescriptor implementation class rather than an ArchiveDescriptorFactory.","If you do not need custom archive interpretation, remove the setting entirely - the code falls back to new StandardArchiveDescriptorFactory()."],"exampleFix":"// before\nsettings.put( PersistenceSettings.SCANNER_ARCHIVE_INTERPRETER, NestedJarDescriptor.class );\n// NestedJarDescriptor is an ArchiveDescriptor (wrong type) or lacks a no-arg ctor\n\n// after\npublic NestedJarDescriptorFactory() {}\nsettings.put( PersistenceSettings.SCANNER_ARCHIVE_INTERPRETER, new NestedJarDescriptorFactory() );\n// or simply omit the setting to use StandardArchiveDescriptorFactory","handlingStrategy":"validation","validationCode":"Class<?> impl = NestedJarDescriptorFactory.class;\nif ( !org.hibernate.boot.archive.scan.spi.ArchiveDescriptorFactory.class.isAssignableFrom( impl ) )\n    throw new IllegalArgumentException( \"supply an ArchiveDescriptorFactory, not an ArchiveDescriptor\" );\nimpl.getDeclaredConstructor();","typeGuard":"static boolean safeInterpreterSetting(Object setting) {\n    return setting instanceof org.hibernate.boot.archive.scan.spi.ArchiveDescriptorFactory\n            || ( setting instanceof Class<?> c\n                 && org.hibernate.boot.archive.scan.spi.ArchiveDescriptorFactory.class.isAssignableFrom( c ) );\n}","tryCatchPattern":"try { ssr = ssrb.build(); }\ncatch ( HibernateException e ) {\n    if ( e.getMessage() != null && e.getMessage().startsWith( \"Unable to instantiate configured ArchiveDescriptorFactory\" ) ) {\n        // cause: ClassCastException = wrong interface; NoSuchMethodException = no no-arg ctor\n    }\n    throw e;\n}","preventionTips":["Remember the factory-vs-descriptor distinction: hibernate.archive.interpreter takes an ArchiveDescriptorFactory.","Omit the setting when standard archive handling suffices - StandardArchiveDescriptorFactory is the default.","Pass an instance to avoid reflection on constructors."],"tags":["hibernate","bootstrap","archive-scanning","reflection","instantiation"],"backgroundTag":"reflection-instantiation-failure","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}