hibernate/hibernate-orm · error · SchemaManagementException

Error resolving legacy import resource : %s

Error message

Error resolving legacy import resource : %s

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/tool/schema/internal/AbstractSchemaPopulator.java:187

						formatter,
						targets
				);
			}
		}
	}

	private ScriptSourceInput interpretLegacyImportScriptSetting(
			String resourceName,
			ClassLoaderService classLoaderService,
			String charsetName) {
		try {
			final URL resourceUrl = classLoaderService.locateResource( resourceName );
			return resourceUrl == null
					? ScriptSourceInputNonExistentImpl.INSTANCE
					: new ScriptSourceInputFromUrl( resourceUrl, charsetName );
		}
		catch (Exception e) {
			throw new SchemaManagementException( "Error resolving legacy import resource : " + resourceName, e );
		}
	}

	/**
	 * @see org.hibernate.cfg.SchemaToolingSettings#HBM2DDL_CHARSET_NAME
	 */
	private static String getCharsetName(ExecutionOptions options) {
		return (String) options.getConfigurationValues().get( HBM2DDL_CHARSET_NAME );
	}

	/**
	 * @see org.hibernate.cfg.SchemaToolingSettings#JAKARTA_HBM2DDL_LOAD_SCRIPT_SOURCE
	 *
	 * @return a {@link java.io.Reader} or a string URL
	 */
	private static Object getImportScriptSetting(ExecutionOptions options) {
		final var configuration = options.getConfigurationValues();
		final Object importScriptSetting = configuration.get( HBM2DDL_LOAD_SCRIPT_SOURCE );

View on GitHub (pinned to fad1729dce)

Solutions

1. Verify the exact resource name resolves at runtime: Thread.currentThread().getContextClassLoader().getResource("<path>") must return non-null in the same environment.
2. Package the script inside the application artifact (src/main/resources) and reference it by its classpath location.
3. Prefer the JPA-standard jakarta.persistence.schema-generation.load-script-source setting over the legacy hibernate.hbm2ddl.import_files.
4. For fat-jar/nested-jar classloader problems, align the packaging plugin or ship the script as a file/URL source instead.

Example fix

# before: legacy import resource not visible to the runtime classloader
hibernate.hbm2ddl.import_files=sql/seed_data.sql

# after: file packaged at src/main/resources/sql/seed_data.sql, referenced by classpath location
hibernate.hbm2ddl.import_files=/sql/seed_data.sql

// At startup, verify the import script resolves in the runtime classloader before schema creation
String path = "/sql/seed_data.sql";
URL url = Thread.currentThread().getContextClassLoader().getResource(path.replaceFirst("^/", ""));
if (url == null) {
    throw new IllegalStateException("Import script not on classpath: " + path);
}

try {
    new SchemaExport(metadata).createOnly(EnumSet.of(TargetType.DATABASE), registry);
} catch (SchemaManagementException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Error resolving legacy import resource")) {
        // inspect getCause() for the classloader failure; fix packaging/classpath, then retry
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Error performing schema management [persistence unit: {}]
• Attempt to resolve foreign key metadata from JDBC metadata f
• Attempt to resolve JDBC metadata failed to find columns for
• Export identifier [%s] encountered more than once
• Halting on error : %s

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/d1aa7f6d5cef88b8. Report an issue: GitHub.