quarkusio/quarkus · error · ConfigurationException

Unable to find file referenced in '${propertyKey}=${classpat

Error message

Unable to find file referenced in '${propertyKey}=${classpathFile}'. Remove property or add file to your path.

What it means

When a config property references a classpath file (e.g. an Elasticsearch analysis or index-settings JSON file), the extension resolves it against the application archive during the build. registerClasspathFileFromConfig throws this ConfigurationException if the referenced path cannot be found under the application root, or if it resolves to a directory instead of a file. This prevents silently shipping a broken native-image resource reference.

Source

Thrown at extensions/hibernate-search-backend-elasticsearch-common/deployment/src/main/java/io/quarkus/hibernate/search/backend/elasticsearch/common/deployment/HibernateSearchBackendElasticsearchProcessor.java:142

                applicationArchivesBuildItem, nativeImageResources, hotDeploymentWatchedFiles);
    }

    private static void registerClasspathFileFromConfig(MapperContext mapperContext, String backendName, String indexName,
            String propertyKeyRadical,
            Optional<String> classpathFileOptional,
            ApplicationArchivesBuildItem applicationArchivesBuildItem,
            BuildProducer<NativeImageResourceBuildItem> nativeImageResources,
            BuildProducer<HotDeploymentWatchedFileBuildItem> hotDeploymentWatchedFiles) {
        if (!classpathFileOptional.isPresent()) {
            return;
        }
        String classpathFile = classpathFileOptional.get();

        Path existingPath = applicationArchivesBuildItem.getRootArchive().getChildPath(classpathFile);

        if (existingPath == null || Files.isDirectory(existingPath)) {
            //raise exception if explicit file is not present (i.e. not the default)
            throw new ConfigurationException(
                    "Unable to find file referenced in '"
                            + mapperContext.backendPropertyKey(backendName, indexName, propertyKeyRadical) + "="
                            + classpathFile
                            + "'. Remove property or add file to your path.");
        }
        nativeImageResources.produce(new NativeImageResourceBuildItem(classpathFile));
        hotDeploymentWatchedFiles.produce(new HotDeploymentWatchedFileBuildItem(classpathFile));
    }

}

View on GitHub (pinned to e1c734241f)

Solutions

1. Place the referenced file under src/main/resources at exactly the path given in the property and rebuild
2. Correct the property value to the existing file's classpath path (check spelling and leading slashes)
3. If the file is not needed, remove the property as the message suggests
4. Verify the path points to a file, not a directory, and that the file is included when building a native image

Example fix

// before
quarkus.hibernate-search-orm.elasticsearch.schema-management.analysis-configurer=analysis/analyzers.json
// after (file actually at src/main/resources/elasticsearch/analyzers.json)
quarkus.hibernate-search-orm.elasticsearch.schema-management.analysis-configurer=elasticsearch/analyzers.json

// Verify resource exists before referencing it in config:
var url = Thread.currentThread().getContextClassLoader().getResource("elasticsearch/analyzers.json");
if (url == null || url.toString().endsWith("/")) {
  throw new IllegalStateException("Referenced Hibernate Search analysis file missing from classpath");
}

When it happens

Trigger: At build time: a property like quarkus.hibernate-search-orm.elasticsearch.schema-management.index-defaults or analysis config file property is set to a classpath path (classpathFile) that either does not exist under the application archive root or points at a directory (existingPath == null || Files.isDirectory(existingPath)).

Common situations: Typo in the resource path; file placed in a module not on the application archive (wrong src/main/resources location); file excluded from the native image; accidentally pointing at a directory instead of a file; renaming/moving resource files without updating config.

Related errors

• The Elasticsearch version needs to be defined via properties
• Multiple instances of %1$s were found for Hibernate Search i
• Multiple instances of %1$s were found for Hibernate Search b
• Failed to open path tree with root %s
• Dev services for ${request.getName()} requires a startable s

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