Starting in Elasticsearch 7.x, colons are no longer allowed in index names. This logic will\n * make sure the pattern in our index template doesn't use them either.\n *\n *
See https://github.com/openzipkin/zipkin/issues/2219\n */\n static char indexTypeDelimiter(ElasticsearchVersion version) {\n return version.compareTo(V7_0) < 0 ? ':' : '-';\n }\n\n @Override String maybeWrap(String type, ElasticsearchVersion version, String json) {\n // ES 7.x defaults include_type_name to false https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes-7.0.html#_literal_include_type_name_literal_now_defaults_to_literal_false_literal\n if (version.compareTo(V7_0) >= 0) return json;\n return \" \\\"\" + type + \"\\\": {\\n \" + json.replace(\"\\n\", \"\\n \") + \" }\\n\";\n }\n\n @Override IndexTemplates get(ElasticsearchVersion version) {\n if (version.compareTo(V5_0) < 0 || version.compareTo(V10_0) >= 0) {\n throw new IllegalArgumentException(\n \"Elasticsearch versions 5-9.x are supported, was: \" + version);\n }\n return IndexTemplates.newBuilder()\n .version(version)\n .indexTypeDelimiter(indexTypeDelimiter(version))\n .span(spanIndexTemplate(version))\n .dependency(dependencyTemplate(version))\n .autocomplete(autocompleteTemplate(version))\n .build();\n }\n}\n","sourceCodeStart":78,"sourceCodeEnd":108,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/ElasticsearchSpecificTemplates.java#L78-L108","documentation":"ElasticsearchSpecificTemplates.get(version) builds the index templates (span, dependency, autocomplete) and only supports Elasticsearch 5.x through 9.x: versions below 5.0.0 or 10.0.0 and above are rejected with IllegalArgumentException. The version compared is the one detected from the cluster, so this fires when the connected cluster identifies itself as an out-of-range Elasticsearch.","triggerScenarios":"Zipkin storage connects to Elasticsearch 2.x/1.x or a future 10.x+ node; ensureIndexTemplatesOrFail() then calls VersionSpecificTemplates.forVersion(...).get(version) and this guard throws. Also happens when an OpenSearch cluster is misidentified as Elasticsearch because .version.distribution was absent (older OpenSearch builds) and the code fell into the Elasticsearch branch.","commonSituations":"Upgrading the Elasticsearch cluster beyond what the bundled Zipkin build supports; running old ES 2.x in legacy environments; connecting to OpenSearch with an old zipkin-server that does not set distribution=opensearch.","solutions":["Upgrade zipkin-server / zipkin-storage-elasticsearch to a release matching your cluster version (each release states its supported ES range).","Or pin the cluster to a supported Elasticsearch 5-9.x version.","If the target is actually OpenSearch, configure STORAGE_TYPE=elasticsearch with ES_VERSION/DISTRIBUTION set to opensearch (or use the opensearch storage mode) so OpensearchSpecificTemplates are used.","Verify with curl GET / what number+distribution the cluster reports and align configuration."],"exampleFix":"# before: zipkin-server 2.x pointed at OpenSearch 2.x detected as elasticsearch\nSTORAGE_TYPE=elasticsearch ES_HOSTS=http://opensearch:9200\n# -> IllegalArgumentException: Elasticsearch versions 5-9.x are supported, was: 2.x\n\n# after\nSTORAGE_TYPE=elasticsearch ES_HOSTS=http://opensearch:9200 ES_VERSION=2.14 OPENSEARCH=true\n# (or upgrade zipkin-server which auto-detects distribution)","handlingStrategy":"validation","validationCode":"// before wiring storage, confirm the cluster version is in the supported ES range\nvar m = java.util.regex.Pattern.compile(\"(\\\\d+)\\\\.(\\\\d+)\\\\..*\").matcher(esVersionNumber);\nif (!m.matches() || Integer.parseInt(m.group(1)) < 5 || Integer.parseInt(m.group(1)) > 9) {\n throw new IllegalStateException(\"Use a zipkin build matching ES \" + esVersionNumber\n + \" or pin the cluster to ES 5-9.x\");\n}","typeGuard":null,"tryCatchPattern":"try {\n ElasticsearchStorage.newBuilder(...).build();\n} catch (IllegalArgumentException e) {\n if (e.getMessage().contains(\"versions 5-9.x are supported\")) {\n // version/distribution mismatch: surface a config error, hint at distribution=opensearch or upgrade\n }\n throw e;\n}","preventionTips":["Check the release notes of your zipkin-server build for its supported ES/OpenSearch matrix before upgrading a cluster.","When using OpenSearch, set the opensearch/distribution flag so the OpenSearch template path is chosen.","Verify GET / reports the expected distribution and number as part of deployment smoke tests."],"tags":["elasticsearch","version-compatibility","index-templates","configuration","storage"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}