More descriptive exception in OldLuceneVersions (elastic#92986)

If we encounter an index that cannot be read by the archive indices
feature then today it's reported as a corrupt index, which typically
sends users down the wrong troubleshooting path. Although this shouldn't
happen, in practice it does sometimes, so this commit adds a descriptive
message to the exception with a link to some docs.

Author: DaveCTurner

server/src/main/java/org/elasticsearch/common/ReferenceDocs.java

@@ -34,6 +34,7 @@ public enum ReferenceDocs {
     UNSTABLE_CLUSTER_TROUBLESHOOTING,
     LAGGING_NODE_TROUBLESHOOTING,
     CONCURRENT_REPOSITORY_WRITERS,
+    ARCHIVE_INDICES,
     // this comment keeps the ';' on the next line so every entry above has a trailing ',' which makes the diff for adding new links cleaner
     ;
 

server/src/main/resources/org/elasticsearch/common/reference-docs-links.json

@@ -3,5 +3,6 @@
   "DISCOVERY_TROUBLESHOOTING": "discovery-troubleshooting.html",
   "UNSTABLE_CLUSTER_TROUBLESHOOTING": "cluster-fault-detection.html#cluster-fault-detection-troubleshooting",
   "LAGGING_NODE_TROUBLESHOOTING": "cluster-fault-detection.html#_diagnosing_lagging_nodes",
-  "CONCURRENT_REPOSITORY_WRITERS": "add-repository.html"
+  "CONCURRENT_REPOSITORY_WRITERS": "add-repository.html",
+  "ARCHIVE_INDICES": "archive-indices.html"
 }

x-pack/plugin/old-lucene-versions/src/main/java/org/elasticsearch/xpack/lucene/bwc/OldLuceneVersions.java

@@ -21,6 +21,8 @@
 import org.elasticsearch.cluster.routing.allocation.AllocationService;
 import org.elasticsearch.cluster.routing.allocation.decider.AllocationDecider;
 import org.elasticsearch.cluster.service.ClusterService;
+import org.elasticsearch.common.ReferenceDocs;
+import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.UUIDs;
 import org.elasticsearch.common.io.stream.NamedWriteableRegistry;
 import org.elasticsearch.common.lucene.Lucene;
@@ -191,7 +193,17 @@ private static void convertToNewFormat(IndexShard indexShard) {
             // clean older segments file
             Lucene.pruneUnreferencedFiles(segmentInfos.getSegmentsFileName(), indexShard.store().directory());
         } catch (IOException e) {
-            throw new UncheckedIOException(e);
+            throw new UncheckedIOException(
+                Strings.format(
+                    """
+                        Elasticsearch version [{}] has limited support for indices created in version [{}] but this index could not be \
+                        read. It may be using an unsupported feature, or it may be damaged or corrupt. See {} for further information.""",
+                    Version.CURRENT,
+                    IndexMetadata.SETTING_INDEX_VERSION_CREATED.get(indexShard.indexSettings().getSettings()),
+                    ReferenceDocs.ARCHIVE_INDICES
+                ),
+                e
+            );
         } finally {
             indexShard.store().decRef();
         }