elastic · elasticsearchmachine · Mar 7, 2025 · Mar 7, 2025
diff --git a/...sitory-s3/src/test/java/org/elasticsearch/repositories/s3/RepositoryCredentialsTests.java b/...sitory-s3/src/test/java/org/elasticsearch/repositories/s3/RepositoryCredentialsTests.java
@@ -107,8 +107,10 @@ public void testRepositoryCredentialsOverrideSecureCredentials() {
         assertThat(credentials.getAWSSecretKey(), is("insecure_aws_secret"));
 
         assertCriticalWarnings(
-            "[access_key] setting was deprecated in Elasticsearch and will be removed in a future release.",
-            "[secret_key] setting was deprecated in Elasticsearch and will be removed in a future release.",
+            "[access_key] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version.",
+            "[secret_key] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version.",
             S3Repository.INSECURE_CREDENTIALS_DEPRECATION_WARNING
         );
     }
@@ -193,8 +195,10 @@ public void testReinitSecureCredentials() {
 
         if (hasInsecureSettings) {
             assertCriticalWarnings(
-                "[access_key] setting was deprecated in Elasticsearch and will be removed in a future release.",
-                "[secret_key] setting was deprecated in Elasticsearch and will be removed in a future release.",
+                "[access_key] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the breaking changes documentation for the next major version.",
+                "[secret_key] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the breaking changes documentation for the next major version.",
                 S3Repository.INSECURE_CREDENTIALS_DEPRECATION_WARNING
             );
         }

diff --git a/server/src/main/java/org/elasticsearch/common/settings/Setting.java b/server/src/main/java/org/elasticsearch/common/settings/Setting.java
@@ -25,7 +25,6 @@
 import org.elasticsearch.core.TimeValue;
 import org.elasticsearch.core.Tuple;
 import org.elasticsearch.core.UpdateForV10;
-import org.elasticsearch.core.UpdateForV9;
 import org.elasticsearch.index.mapper.DateFieldMapper;
 import org.elasticsearch.xcontent.ToXContentObject;
 import org.elasticsearch.xcontent.XContentBuilder;
@@ -83,6 +82,11 @@
  * </pre>
  */
 public class Setting<T> implements ToXContentObject {
+    private static final String DEPRECATED_MESSAGE_TEMPLATE =
+        "[{}] setting was deprecated in Elasticsearch and will be removed in a future release. "
+            + "See the %s documentation for the next major version.";
+    private static final String DEPRECATED_WARN_MESSAGE = Strings.format(DEPRECATED_MESSAGE_TEMPLATE, "deprecation");
+    private static final String DEPRECATED_CRITICAL_MESSAGE = Strings.format(DEPRECATED_MESSAGE_TEMPLATE, "breaking changes");
 
     public enum Property {
         /**
@@ -651,10 +655,8 @@ void checkDeprecation(Settings settings) {
         if (this.isDeprecated() && this.exists(settings)) {
             // It would be convenient to show its replacement key, but replacement is often not so simple
             final String key = getKey();
-            @UpdateForV9(owner = UpdateForV9.Owner.CORE_INFRA) // https://github.com/elastic/elasticsearch/issues/79666
-            String message = "[{}] setting was deprecated in Elasticsearch and will be removed in a future release.";
             if (this.isDeprecatedWarningOnly()) {
-                Settings.DeprecationLoggerHolder.deprecationLogger.warn(DeprecationCategory.SETTINGS, key, message, key);
+                Settings.DeprecationLoggerHolder.deprecationLogger.warn(DeprecationCategory.SETTINGS, key, DEPRECATED_WARN_MESSAGE, key);
             } else if (this.isDeprecatedAndRemoved()) {
                 Settings.DeprecationLoggerHolder.deprecationLogger.critical(
                     DeprecationCategory.SETTINGS,
@@ -663,7 +665,12 @@ void checkDeprecation(Settings settings) {
                     key
                 );
             } else {
-                Settings.DeprecationLoggerHolder.deprecationLogger.critical(DeprecationCategory.SETTINGS, key, message, key);
+                Settings.DeprecationLoggerHolder.deprecationLogger.critical(
+                    DeprecationCategory.SETTINGS,
+                    key,
+                    DEPRECATED_CRITICAL_MESSAGE,
+                    key
+                );
             }
         }
     }

diff --git a/server/src/test/java/org/elasticsearch/cluster/ClusterModuleTests.java b/server/src/test/java/org/elasticsearch/cluster/ClusterModuleTests.java
@@ -189,7 +189,8 @@ public void testRegisterShardsAllocator() {
         ClusterModule module = newClusterModuleWithShardsAllocator(settings, "custom", FakeShardsAllocator::new);
         assertEquals(FakeShardsAllocator.class, module.shardsAllocator.getClass());
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 
@@ -219,15 +220,17 @@ public void testUnknownShardsAllocator() {
         );
         assertEquals("Unknown ShardsAllocator [dne]", e.getMessage());
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 
     public void testShardsAllocatorFactoryNull() {
         Settings settings = Settings.builder().put(ClusterModule.SHARDS_ALLOCATOR_TYPE_SETTING.getKey(), "bad").build();
         expectThrows(NullPointerException.class, () -> newClusterModuleWithShardsAllocator(settings, "bad", () -> null));
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 

diff --git a/.../test/java/org/elasticsearch/cluster/routing/allocation/ClusterRebalanceRoutingTests.java b/.../test/java/org/elasticsearch/cluster/routing/allocation/ClusterRebalanceRoutingTests.java
@@ -704,7 +704,8 @@ public void beforeAllocation(RoutingAllocation allocation) {
             }
         );
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
 
         Metadata metadata = Metadata.builder()

diff --git a/server/src/test/java/org/elasticsearch/cluster/routing/allocation/IndexBalanceTests.java b/server/src/test/java/org/elasticsearch/cluster/routing/allocation/IndexBalanceTests.java
@@ -449,7 +449,8 @@ public void testRebalanceShouldNotPerformUnnecessaryMovesWithMultipleConcurrentR
 
         final var allocationService = createAllocationService(settings);
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
 
         assertTrue(

diff --git a/...src/test/java/org/elasticsearch/cluster/routing/allocation/ThrottlingAllocationTests.java b/...src/test/java/org/elasticsearch/cluster/routing/allocation/ThrottlingAllocationTests.java
@@ -200,7 +200,8 @@ public void testThrottleIncomingAndOutgoing() {
             snapshotsInfoService
         );
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
         logger.info("Building initial routing table");
 

diff --git a/server/src/test/java/org/elasticsearch/index/codec/PerFieldMapperCodecTests.java b/server/src/test/java/org/elasticsearch/index/codec/PerFieldMapperCodecTests.java
@@ -112,7 +112,8 @@ public void testUseBloomFilterWithTimestampFieldEnabled_disableBloomFilter() thr
         assertThat(perFieldMapperCodec.useBloomFilter("_id"), is(false));
         assertThat(perFieldMapperCodec.getPostingsFormatForField("_id"), instanceOf(ES812PostingsFormat.class));
         assertWarnings(
-            "[index.bloom_filter_for_id_field.enabled] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[index.bloom_filter_for_id_field.enabled] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the deprecation documentation for the next major version."
         );
     }
 

diff --git a/server/src/test/java/org/elasticsearch/snapshots/InternalSnapshotsInfoServiceTests.java b/server/src/test/java/org/elasticsearch/snapshots/InternalSnapshotsInfoServiceTests.java
@@ -362,7 +362,8 @@ public IndexShardSnapshotStatus.Copy getShardSnapshotStatus(SnapshotId snapshotI
                 snapshotsInfoService
             );
             assertCriticalWarnings(
-                "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+                "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the breaking changes documentation for the next major version."
             );
             applyClusterState(
                 "starting shards for " + indexName,

diff --git a/server/src/test/java/org/elasticsearch/snapshots/SnapshotResiliencyTests.java b/server/src/test/java/org/elasticsearch/snapshots/SnapshotResiliencyTests.java
@@ -2202,7 +2202,8 @@ public RecyclerBytesStreamOutput newNetworkBytesStream() {
                     snapshotsInfoService
                 );
                 assertCriticalWarnings(
-                    "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+                    "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                        + "See the breaking changes documentation for the next major version."
                 );
                 rerouteService = new BatchedRerouteService(clusterService, allocationService::reroute);
                 rerouteServiceSetOnce.set(rerouteService);

diff --git a/server/src/test/java/org/elasticsearch/transport/TransportServiceLifecycleTests.java b/server/src/test/java/org/elasticsearch/transport/TransportServiceLifecycleTests.java
@@ -171,7 +171,8 @@ public void testInternalSendExceptionForksToGenericIfHandlerDoesNotForkAndStackO
             assertEquals("simulated exception in sendRequest", getSendRequestException(future, IOException.class).getMessage());
         }
         assertWarnings(
-            "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 
@@ -264,7 +265,8 @@ public void testOnConnectionClosedUsesHandlerExecutor() {
         onConnectionClosedUsesHandlerExecutor(settings, executorName, expectedExecutor);
         if (withSetting) {
             assertWarnings(
-                "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release."
+                "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the breaking changes documentation for the next major version."
             );
         }
     }
@@ -276,7 +278,8 @@ public void testOnConnectionCloseStackOverflowAvoidance() {
             ThreadPool.Names.GENERIC
         );
         assertWarnings(
-            "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 

diff --git a/test/framework/src/main/java/org/elasticsearch/test/ESSingleNodeTestCase.java b/test/framework/src/main/java/org/elasticsearch/test/ESSingleNodeTestCase.java
@@ -234,7 +234,10 @@ protected boolean addMockHttpTransport() {
     protected List<String> filteredWarnings() {
         return Stream.concat(
             super.filteredWarnings().stream(),
-            Stream.of("[index.data_path] setting was deprecated in Elasticsearch and will be removed in a future release.")
+            Stream.of(
+                "[index.data_path] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the deprecation documentation for the next major version."
+            )
         ).collect(Collectors.toList());
     }
 

diff --git a/test/framework/src/main/java/org/elasticsearch/test/ESTestCase.java b/test/framework/src/main/java/org/elasticsearch/test/ESTestCase.java
@@ -699,15 +699,14 @@ protected List<String> filteredWarnings() {
      */
     protected final void assertSettingDeprecationsAndWarnings(final Setting<?>[] settings, final DeprecationWarning... warnings) {
         assertWarnings(true, Stream.concat(Arrays.stream(settings).map(setting -> {
-            String warningMessage = String.format(
-                Locale.ROOT,
-                "[%s] setting was deprecated in Elasticsearch and will be removed in a future release.",
-                setting.getKey()
-            );
-            return new DeprecationWarning(
-                setting.getProperties().contains(Setting.Property.Deprecated) ? DeprecationLogger.CRITICAL : Level.WARN,
-                warningMessage
+            Level level = setting.getProperties().contains(Setting.Property.Deprecated) ? DeprecationLogger.CRITICAL : Level.WARN;
+            String warningMessage = Strings.format(
+                "[%s] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the %s documentation for the next major version.",
+                setting.getKey(),
+                (level == Level.WARN) ? "deprecation" : "breaking changes"
             );
+            return new DeprecationWarning(level, warningMessage);
         }), Arrays.stream(warnings)).toArray(DeprecationWarning[]::new));
     }
 

diff --git a/...r/src/test/java/org/elasticsearch/xpack/monitoring/collector/ccr/StatsCollectorTests.java b/...r/src/test/java/org/elasticsearch/xpack/monitoring/collector/ccr/StatsCollectorTests.java
@@ -152,7 +152,7 @@ public void testDoCollect() throws Exception {
 
         assertWarnings(
             "[xpack.monitoring.collection.ccr.stats.timeout] setting was deprecated in Elasticsearch and will be removed in "
-                + "a future release."
+                + "a future release. See the deprecation documentation for the next major version."
         );
     }
 

diff --git a/.../qa/rest/src/javaRestTest/java/org/elasticsearch/xpack/deprecation/DeprecationHttpIT.java b/.../qa/rest/src/javaRestTest/java/org/elasticsearch/xpack/deprecation/DeprecationHttpIT.java
@@ -130,7 +130,8 @@ public void testDeprecatedSettingsReturnWarnings() throws Exception {
     }
 
     private Matcher<String> matchDeprecationWarning(Setting<?> setting) {
-        var format = "[%s] setting was deprecated in Elasticsearch and will be removed in a future release.";
+        var format = "[%s] setting was deprecated in Elasticsearch and will be removed in a future release. "
+            + "See the deprecation documentation for the next major version.";
         return equalTo(Strings.format(format, setting.getKey()));
     }
 

diff --git a/...ecation/src/test/java/org/elasticsearch/xpack/deprecation/NodeDeprecationChecksTests.java b/...ecation/src/test/java/org/elasticsearch/xpack/deprecation/NodeDeprecationChecksTests.java
@@ -591,8 +591,9 @@ public void testScriptContextCompilationsRateLimitSetting() {
 
         assertWarnings(
             "[script.context.field.max_compilations_rate] setting was deprecated in Elasticsearch and will be"
-                + " removed in a future release.",
-            "[script.context.score.max_compilations_rate] setting was deprecated in Elasticsearch and will be removed in a future release."
+                + " removed in a future release. See the deprecation documentation for the next major version.",
+            "[script.context.score.max_compilations_rate] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the deprecation documentation for the next major version."
         );
     }
 
@@ -628,8 +629,9 @@ public void testImplicitScriptContextCacheSetting() {
 
         assertWarnings(
             "[script.context.update.max_compilations_rate] setting was deprecated in Elasticsearch and will be"
-                + " removed in a future release.",
-            "[script.context.filter.cache_max_size] setting was deprecated in Elasticsearch and will be removed in a future release."
+                + " removed in a future release. See the deprecation documentation for the next major version.",
+            "[script.context.filter.cache_max_size] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the deprecation documentation for the next major version."
         );
     }
 
@@ -665,8 +667,10 @@ public void testScriptContextCacheSizeSetting() {
         );
 
         assertWarnings(
-            "[script.context.update.cache_max_size] setting was deprecated in Elasticsearch and will be removed in a future release.",
-            "[script.context.filter.cache_max_size] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[script.context.update.cache_max_size] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the deprecation documentation for the next major version.",
+            "[script.context.filter.cache_max_size] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the deprecation documentation for the next major version."
         );
     }
 
@@ -702,8 +706,10 @@ public void testScriptContextCacheExpirationSetting() {
         );
 
         assertWarnings(
-            "[script.context.interval.cache_expire] setting was deprecated in Elasticsearch and will be removed in a future release.",
+            "[script.context.interval.cache_expire] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the deprecation documentation for the next major version.",
             "[script.context.moving-function.cache_expire] setting was deprecated in Elasticsearch and will be removed in a future release."
+                + " See the deprecation documentation for the next major version."
         );
     }
 
@@ -760,7 +766,8 @@ public void testLifecyleStepMasterTimeoutSetting() {
             true,
             new DeprecationWarning(
                 Level.WARN,
-                "[indices.lifecycle.step.master_timeout] setting was deprecated in Elasticsearch and will be removed in a future release."
+                "[indices.lifecycle.step.master_timeout] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the deprecation documentation for the next major version."
             )
         );
     }
@@ -782,7 +789,8 @@ public void testEqlEnabledSetting() {
             true,
             new DeprecationWarning(
                 Level.WARN,
-                "[xpack.eql.enabled] setting was deprecated in Elasticsearch and will be removed in a future release."
+                "[xpack.eql.enabled] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the deprecation documentation for the next major version."
             )
         );
     }

diff --git a/x-pack/plugin/enrich/src/test/java/org/elasticsearch/xpack/enrich/EnrichPluginTests.java b/x-pack/plugin/enrich/src/test/java/org/elasticsearch/xpack/enrich/EnrichPluginTests.java
@@ -53,7 +53,10 @@ public void testConstructWithBothSettings() {
     @Override
     protected List<String> filteredWarnings() {
         final var warnings = super.filteredWarnings();
-        warnings.add("[enrich.cache.size] setting was deprecated in Elasticsearch and will be removed in a future release.");
+        warnings.add(
+            "[enrich.cache.size] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
+        );
         warnings.add(
             "The [enrich.cache.size] setting is deprecated and will be removed in a future version. Please use [enrich.cache_size] instead."
         );

diff --git a/...t/java/org/elasticsearch/xpack/monitoring/collector/enrich/EnrichStatsCollectorTests.java b/...t/java/org/elasticsearch/xpack/monitoring/collector/enrich/EnrichStatsCollectorTests.java
@@ -146,7 +146,7 @@ public void testDoCollect() throws Exception {
 
         assertWarnings(
             "[xpack.monitoring.collection.enrich.stats.timeout] setting was deprecated in Elasticsearch and will be removed "
-                + "in a future release."
+                + "in a future release. See the deprecation documentation for the next major version."
         );
     }