quarkusio/quarkus · error · ConfigurationException

Unable to interpret path referenced in '<puPropertyKey(persi

Error message

Unable to interpret path referenced in '<puPropertyKey(persistenceUnitName, "sql-load-script")>=<sqlLoadScript>': <e.getMessage()>

What it means

The SQL load script configured via quarkus.hibernate-orm."<pu>".sql-load-script is resolved against the application root archive. If resolving the path throws a RuntimeException, configureSqlLoadScript wraps it into a ConfigurationException that echoes the property key, the configured value(s), and the underlying error message.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/util/HibernateProcessorSupport.java:489

    public static void configureSqlLoadScript(String persistenceUnitName,
            HibernateOrmConfigPersistenceUnit persistenceUnitConfig,
            ApplicationArchivesBuildItem applicationArchivesBuildItem, LaunchMode launchMode,
            List<SqlLoadScriptDefaultBuildItem> additionalSqlLoadScriptDefaults,
            BuildProducer<NativeImageResourceBuildItem> nativeImageResources,
            BuildProducer<HotDeploymentWatchedFileBuildItem> hotDeploymentWatchedFiles,
            QuarkusPersistenceUnitDescriptor descriptor) {
        // This defaults to 'import.sql', and potentially 'data.sql', in non-production modes
        List<String> importFiles = getSqlLoadScript(persistenceUnitConfig.sqlLoadScript(),
                launchMode, persistenceUnitName, additionalSqlLoadScriptDefaults);
        if (!importFiles.isEmpty()) {
            List<String> existingImportFiles = new ArrayList<>();
            for (String importFile : importFiles) {
                Path loadScriptPath;
                try {
                    loadScriptPath = applicationArchivesBuildItem.getRootArchive().getChildPath(importFile);
                } catch (RuntimeException e) {
                    throw new ConfigurationException(
                            "Unable to interpret path referenced in '"
                                    + HibernateOrmRuntimeConfig.puPropertyKey(persistenceUnitName, "sql-load-script") + "="
                                    + String.join(",", persistenceUnitConfig.sqlLoadScript().get())
                                    + "': " + e.getMessage());
                }

                if (loadScriptPath != null && !Files.isDirectory(loadScriptPath)) {
                    // enlist resource if present
                    existingImportFiles.add(importFile);
                    nativeImageResources.produce(new NativeImageResourceBuildItem(importFile));
                } else if (persistenceUnitConfig.sqlLoadScript().isPresent()) {
                    //raise exception if explicit file is not present (i.e. not the default)
                    throw new ConfigurationException(
                            "Unable to find file referenced in '"
                                    + HibernateOrmRuntimeConfig.puPropertyKey(persistenceUnitName, "sql-load-script") + "="
                                    + String.join(",", persistenceUnitConfig.sqlLoadScript().get())
                                    + "'. Remove property or add file to your path.");
                }

View on GitHub (pinned to e1c734241f)

Solutions

1. Use a classpath-relative path that exists in the application (e.g. import.sql in src/main/resources)
2. Remove absolute paths, URLs, or protocol prefixes from the sql-load-script value
3. Check the nested e.getMessage() in the error for the exact path problem
4. Place the script under src/main/resources so it is packaged into the archive

Example fix

// before
quarkus.hibernate-orm.sql-load-script=file:/home/me/scripts/import.sql
// after
quarkus.hibernate-orm.sql-load-script=import.sql

// Check the script exists at a classpath-relative location before configuring
var url = Thread.currentThread().getContextClassLoader().getResource("import.sql");
if (url == null) throw new IllegalStateException("import.sql not found in classpath");

When it happens

Trigger: configureSqlLoadScript calls getRootArchive().getChildPath(importFile) for each sql-load-script entry and the archive throws while interpreting the path (malformed path expression).

Common situations: Absolute paths or URLs in sql-load-script; paths with unsupported characters or double slashes; referencing files outside the application archive; typos like 'file:/...' protocol prefixes.

Related errors

• Cannot find ORM mapping file '${mappingFileName}' in the cla
• Missing attribute '${nodeName}.class'
• Annotation ${dotName} was not expected on a target of kind $
• Type ${className} must be annotated with @Embeddable, becaus
• Multiple ${AdditionalPersistenceUnitBuildItem} for persisten

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/bce74f95a75f7822. Report an issue: GitHub.