What causes "Unable to find file referenced in ' = '. Remove property or add file to your path." in quarkusio/quarkus?

Create the referenced file at the configured path inside src/main/resources so it is packaged on the classpath.

quarkusio/quarkus · error · ConfigurationException

Unable to find file referenced in '<puPropertyKey(persistenc

Error message

Unable to find file referenced in '<puPropertyKey(persistenceUnitName, "sql-load-script")>=<sqlLoadScript>'. Remove property or add file to your path.

What it means

Quarkus Hibernate ORM throws this when the SQL load script configured via quarkus.hibernate-orm.<pu>.sql-load-script does not exist at build time. Unlike the default import.sql, an explicitly configured script must resolve to an existing file on the path; the build fails fast so the misconfiguration is caught before runtime. The message includes the exact property key and configured value.

Source

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

            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.");
                }
                // in dev mode we want to make sure that we watch for changes to file even if it doesn't currently exist
                // as a user could still add it after performing the initial configuration
                hotDeploymentWatchedFiles.produce(new HotDeploymentWatchedFileBuildItem(importFile));
            }

            if (!existingImportFiles.isEmpty()) {
                descriptor.getProperties().setProperty(AvailableSettings.JAKARTA_HBM2DDL_LOAD_SCRIPT_SOURCE,
                        String.join(",", existingImportFiles));
            }
        }

        //Disable implicit loading of the default import script (import.sql)
        descriptor.getProperties().setProperty(AvailableSettings.HBM2DDL_SKIP_DEFAULT_IMPORT_FILE, "true");

View on GitHub (pinned to e1c734241f)

Solutions

Create the referenced file at the configured path inside src/main/resources so it is packaged on the classpath.
Correct the sql-load-script value to the actual file name/path.
Remove the sql-load-script property entirely, or set it to 'no-file' to disable script loading.
Verify the file is not a directory and is readable at build time.

Example fix

// before (application.properties)
quarkus.hibernate-orm.sql-load-script=my-imports.sql  // file missing
// after
quarkus.hibernate-orm.sql-load-script=sql/my-imports.sql  // exists in src/main/resources/sql/
// or disable: quarkus.hibernate-orm.sql-load-script=no-file

Defensive patterns

Strategy: validation

Validate before calling

String script = "sql/my-imports.sql";
try (var in = Thread.currentThread().getContextClassLoader().getResourceAsStream(script)) {
    if (in == null) throw new IllegalStateException("sql-load-script not on classpath: " + script);
}

Prevention

Keep sql-load-script files under src/main/resources so they are always packaged.
Add a CI/build check that every configured script exists on the classpath.
Use the documented 'no-file' value to disable loading instead of a bogus path.
Never point sql-load-script at a directory.

When it happens

Trigger: configureSqlLoadScript raises ConfigurationException when the sql-load-script property is explicitly present but loadScriptPath is missing or a directory, so no resource can be enlisted for the persistence unit.

Common situations: Typo in the script filename; script placed outside src/main/resources so it never lands on the classpath; file only present in src/test; configured value points at a directory; dev-mode file deleted while the property remains set.

Related errors

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