{"record":{"id":"d1aa7f6d5cef88b8","repo":"hibernate/hibernate-orm","slug":"error-resolving-legacy-import-resource-s","errorCode":null,"errorMessage":"Error resolving legacy import resource : %s","messagePattern":"Error resolving legacy import resource : (.+?)","errorType":"exception","errorClass":"SchemaManagementException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/tool/schema/internal/AbstractSchemaPopulator.java","lineNumber":187,"sourceCode":"\t\t\t\t\t\tformatter,\n\t\t\t\t\t\ttargets\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate ScriptSourceInput interpretLegacyImportScriptSetting(\n\t\t\tString resourceName,\n\t\t\tClassLoaderService classLoaderService,\n\t\t\tString charsetName) {\n\t\ttry {\n\t\t\tfinal URL resourceUrl = classLoaderService.locateResource( resourceName );\n\t\t\treturn resourceUrl == null\n\t\t\t\t\t? ScriptSourceInputNonExistentImpl.INSTANCE\n\t\t\t\t\t: new ScriptSourceInputFromUrl( resourceUrl, charsetName );\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new SchemaManagementException( \"Error resolving legacy import resource : \" + resourceName, e );\n\t\t}\n\t}\n\n\t/**\n\t * @see org.hibernate.cfg.SchemaToolingSettings#HBM2DDL_CHARSET_NAME\n\t */\n\tprivate static String getCharsetName(ExecutionOptions options) {\n\t\treturn (String) options.getConfigurationValues().get( HBM2DDL_CHARSET_NAME );\n\t}\n\n\t/**\n\t * @see org.hibernate.cfg.SchemaToolingSettings#JAKARTA_HBM2DDL_LOAD_SCRIPT_SOURCE\n\t *\n\t * @return a {@link java.io.Reader} or a string URL\n\t */\n\tprivate static Object getImportScriptSetting(ExecutionOptions options) {\n\t\tfinal var configuration = options.getConfigurationValues();\n\t\tfinal Object importScriptSetting = configuration.get( HBM2DDL_LOAD_SCRIPT_SOURCE );","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/tool/schema/internal/AbstractSchemaPopulator.java#L169-L205","documentation":"SchemaManagementException thrown while resolving a legacy import script resource (hibernate.hbm2ddl.import_files, processed by AbstractSchemaPopulator during schema creation): ClassLoaderService.locateResource() itself threw an unexpected exception. Note a merely-missing resource does NOT throw here - it maps to a non-existent input and is skipped - so this error points at a classloader/environment failure while looking the resource up.","triggerScenarios":"Schema creation with hibernate.hbm2ddl.auto=create/create-drop (or the JPA jakarta.persistence.schema-generation.load-script-source variant handled by the same populator) where locateResource throws: restrictive or custom classloaders (app servers, fat jars with nested-resource protocols), thread-context classloader not seeing the persistence unit's resources, or a malformed resource path that breaks the locator.","commonSituations":"Running schema creation inside an app server or bootable jar whose classloader cannot resolve classpath URLs the way Hibernate's AggregatedClassLoader expects; script referenced with a path that resolves differently at runtime than in IDE; deploying the import script outside the application artifact.","solutions":["Verify the exact resource name resolves at runtime: Thread.currentThread().getContextClassLoader().getResource(\"<path>\") must return non-null in the same environment.","Package the script inside the application artifact (src/main/resources) and reference it by its classpath location.","Prefer the JPA-standard jakarta.persistence.schema-generation.load-script-source setting over the legacy hibernate.hbm2ddl.import_files.","For fat-jar/nested-jar classloader problems, align the packaging plugin or ship the script as a file/URL source instead."],"exampleFix":"# before: legacy import resource not visible to the runtime classloader\nhibernate.hbm2ddl.import_files=sql/seed_data.sql\n\n# after: file packaged at src/main/resources/sql/seed_data.sql, referenced by classpath location\nhibernate.hbm2ddl.import_files=/sql/seed_data.sql","handlingStrategy":"validation","validationCode":"// At startup, verify the import script resolves in the runtime classloader before schema creation\nString path = \"/sql/seed_data.sql\";\nURL url = Thread.currentThread().getContextClassLoader().getResource(path.replaceFirst(\"^/\", \"\"));\nif (url == null) {\n    throw new IllegalStateException(\"Import script not on classpath: \" + path);\n}","typeGuard":null,"tryCatchPattern":"try {\n    new SchemaExport(metadata).createOnly(EnumSet.of(TargetType.DATABASE), registry);\n} catch (SchemaManagementException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Error resolving legacy import resource\")) {\n        // inspect getCause() for the classloader failure; fix packaging/classpath, then retry\n    }\n    throw e;\n}","preventionTips":["Package import scripts inside the application artifact (src/main/resources) so they share the persistence unit's classloader","Prefer the JPA-standard jakarta.persistence.schema-generation.load-script-source over legacy hibernate.hbm2ddl.import_files","Add a startup assertion that resolves every configured script resource before enabling ddl-auto=create"],"tags":["hibernate","schema-management","import-script","classpath-resource","hbm2ddl"],"backgroundTag":"classpath-resource-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}