quarkusio/quarkus · error · ConfigurationException

The Elasticsearch version needs to be defined via properties

Error message

The Elasticsearch version needs to be defined via properties: ${propertyKeysWithNoVersion}.

What it means

The Quarkus Hibernate Search Elasticsearch extension requires every Elasticsearch backend (and schema-management target) to have an explicit version defined. During the deployment build step processBuildTimeConfig, the processor collects property keys that reference Elasticsearch hosts/backends but carry no version information; if any remain, it aborts the build with a ConfigurationException listing the offending property keys. This guarantees consistent schema generation/analysis against a known Elasticsearch version.

Source

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

        var mapperContext = enabled.getMapperContext();
        Set<String> allBackendNames = new LinkedHashSet<>(mapperContext.getBackendNamesForIndexedEntities());
        allBackendNames.addAll(buildTimeConfig.keySet());
        // For all backends referenced either through @Indexed(backend = ...) or configuration...
        for (String backendName : allBackendNames) {
            HibernateSearchBackendElasticsearchBuildTimeConfig backendConfig = buildTimeConfig.get(backendName);
            // ... we validate that the backend is configured and the version is present
            if (backendConfig == null || backendConfig.version().isEmpty()) {
                propertyKeysWithNoVersion.add(mapperContext.backendPropertyKey(backendName, null, "version"));
            }
            if (backendConfig == null) {
                continue;
            }
            // ... we register files referenced from backends configuration
            registerClasspathFilesFromBackendConfig(mapperContext, backendName, backendConfig,
                    applicationArchivesBuildItem, nativeImageResources, hotDeploymentWatchedFiles);
        }
        if (!propertyKeysWithNoVersion.isEmpty()) {
            throw new ConfigurationException(
                    "The Elasticsearch version needs to be defined via properties: "
                            + String.join(", ", propertyKeysWithNoVersion) + ".",
                    propertyKeysWithNoVersion);
        }
    }

    private static void registerClasspathFilesFromBackendConfig(MapperContext mapperContext, String backendName,
            HibernateSearchBackendElasticsearchBuildTimeConfig backendConfig,
            ApplicationArchivesBuildItem applicationArchivesBuildItem,
            BuildProducer<NativeImageResourceBuildItem> nativeImageResources,
            BuildProducer<HotDeploymentWatchedFileBuildItem> hotDeploymentWatchedFiles) {
        registerClasspathFilesFromIndexConfig(mapperContext, backendName, null, backendConfig.indexDefaults(),
                applicationArchivesBuildItem, nativeImageResources, hotDeploymentWatchedFiles);
        for (Entry<String, HibernateSearchBackendElasticsearchBuildTimeConfig.IndexConfig> entry : backendConfig.indexes()
                .entrySet()) {
            String indexName = entry.getKey();
            HibernateSearchBackendElasticsearchBuildTimeConfig.IndexConfig indexConfig = entry.getValue();
            registerClasspathFilesFromIndexConfig(mapperContext, backendName, indexName, indexConfig,

View on GitHub (pinned to e1c734241f)

Solutions

Add quarkus.hibernate-search-orm.elasticsearch.version (or the backend-specific variant named in the message) to application.properties, e.g. quarkus.hibernate-search-orm.elasticsearch.version=8
If the property was set by mistake (leftover host/url config for an unused backend), remove the listed property keys entirely
Check for typos in the version property key so it is actually associated with the backend referenced in the error

Example fix

// before
quarkus.hibernate-search-orm.elasticsearch.hosts=localhost:9200
// after
quarkus.hibernate-search-orm.elasticsearch.hosts=localhost:9200
quarkus.hibernate-search-orm.elasticsearch.version=8

Defensive patterns

Strategy: validation

Validate before calling

// Check before building:
if (config.getProperty("quarkus.hibernate-search-orm.elasticsearch.hosts") != null
    && config.getProperty("quarkus.hibernate-search-orm.elasticsearch.version") == null) {
  throw new IllegalStateException("Set quarkus.hibernate-search-orm.elasticsearch.version when configuring Elasticsearch hosts");
}

Prevention

Always define quarkus.hibernate-search-orm.elasticsearch.version whenever any backend property is set
Keep all backend settings grouped together in application.properties so version isn't forgotten
Run the application build early in CI to catch build-time config errors immediately

When it happens

Trigger: At application build time: a quarkus.hibernate-search-orm.elasticsearch.version.* related property (e.g. hosts, url) is set for a backend, but the corresponding quarkus.hibernate-search-orm.elasticsearch.version property is absent, so propertyKeysWithNoVersion is non-empty when processBuildTimeConfig finishes.

Common situations: Configuring elasticsearch hosts or schema management settings while forgetting the version property; copying backend config from a multi-backend setup and dropping the version line; enabling a schema-management feature (index-defaults, analysis config from files) that implies a version requirement.

Related errors

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