{"record":{"id":"0e61f75547c96b31","repo":"quarkusio/quarkus","slug":"the-elasticsearch-version-needs-to-be-defined-via","errorCode":null,"errorMessage":"The Elasticsearch version needs to be defined via properties: ${propertyKeysWithNoVersion}.","messagePattern":"The Elasticsearch version needs to be defined via properties: (.+?)\\.","errorType":"exception","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-search-backend-elasticsearch-common/deployment/src/main/java/io/quarkus/hibernate/search/backend/elasticsearch/common/deployment/HibernateSearchBackendElasticsearchProcessor.java","lineNumber":91,"sourceCode":"        var mapperContext = enabled.getMapperContext();\n        Set<String> allBackendNames = new LinkedHashSet<>(mapperContext.getBackendNamesForIndexedEntities());\n        allBackendNames.addAll(buildTimeConfig.keySet());\n        // For all backends referenced either through @Indexed(backend = ...) or configuration...\n        for (String backendName : allBackendNames) {\n            HibernateSearchBackendElasticsearchBuildTimeConfig backendConfig = buildTimeConfig.get(backendName);\n            // ... we validate that the backend is configured and the version is present\n            if (backendConfig == null || backendConfig.version().isEmpty()) {\n                propertyKeysWithNoVersion.add(mapperContext.backendPropertyKey(backendName, null, \"version\"));\n            }\n            if (backendConfig == null) {\n                continue;\n            }\n            // ... we register files referenced from backends configuration\n            registerClasspathFilesFromBackendConfig(mapperContext, backendName, backendConfig,\n                    applicationArchivesBuildItem, nativeImageResources, hotDeploymentWatchedFiles);\n        }\n        if (!propertyKeysWithNoVersion.isEmpty()) {\n            throw new ConfigurationException(\n                    \"The Elasticsearch version needs to be defined via properties: \"\n                            + String.join(\", \", propertyKeysWithNoVersion) + \".\",\n                    propertyKeysWithNoVersion);\n        }\n    }\n\n    private static void registerClasspathFilesFromBackendConfig(MapperContext mapperContext, String backendName,\n            HibernateSearchBackendElasticsearchBuildTimeConfig backendConfig,\n            ApplicationArchivesBuildItem applicationArchivesBuildItem,\n            BuildProducer<NativeImageResourceBuildItem> nativeImageResources,\n            BuildProducer<HotDeploymentWatchedFileBuildItem> hotDeploymentWatchedFiles) {\n        registerClasspathFilesFromIndexConfig(mapperContext, backendName, null, backendConfig.indexDefaults(),\n                applicationArchivesBuildItem, nativeImageResources, hotDeploymentWatchedFiles);\n        for (Entry<String, HibernateSearchBackendElasticsearchBuildTimeConfig.IndexConfig> entry : backendConfig.indexes()\n                .entrySet()) {\n            String indexName = entry.getKey();\n            HibernateSearchBackendElasticsearchBuildTimeConfig.IndexConfig indexConfig = entry.getValue();\n            registerClasspathFilesFromIndexConfig(mapperContext, backendName, indexName, indexConfig,","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-search-backend-elasticsearch-common/deployment/src/main/java/io/quarkus/hibernate/search/backend/elasticsearch/common/deployment/HibernateSearchBackendElasticsearchProcessor.java#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nquarkus.hibernate-search-orm.elasticsearch.hosts=localhost:9200\n// after\nquarkus.hibernate-search-orm.elasticsearch.hosts=localhost:9200\nquarkus.hibernate-search-orm.elasticsearch.version=8","handlingStrategy":"validation","validationCode":"// Check before building:\nif (config.getProperty(\"quarkus.hibernate-search-orm.elasticsearch.hosts\") != null\n    && config.getProperty(\"quarkus.hibernate-search-orm.elasticsearch.version\") == null) {\n  throw new IllegalStateException(\"Set quarkus.hibernate-search-orm.elasticsearch.version when configuring Elasticsearch hosts\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["quarkus","hibernate-search","elasticsearch","build-time-config","configuration-exception"],"backgroundTag":"missing-required-config-property","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}