{"record":{"id":"01cc985c01bc5604","repo":"openzipkin/zipkin","slug":"opensearch-versions-1-3-x-are-supported-was-s","errorCode":null,"errorMessage":"OpenSearch versions 1-3.x are supported, was: %s","messagePattern":"OpenSearch versions 1-3\\.x are supported, was: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/OpensearchSpecificTemplates.java","lineNumber":71,"sourceCode":"      + \"-*\"\n      + \"\\\"\";\n  }\n  \n  static char indexTypeDelimiter(OpensearchVersion version) {\n    return '-';\n  }\n  \n  @Override boolean useComposableTemplate(OpensearchVersion version) {\n    return (templatePriority != null);\n  }\n  \n  @Override String maybeWrap(String type, OpensearchVersion version, String json) {\n    return json;\n  }\n\n  @Override IndexTemplates get(OpensearchVersion version) {\n    if (version.compareTo(V1_0) < 0 || version.compareTo(V4_0) >= 0) {\n      throw new IllegalArgumentException(\n        \"OpenSearch versions 1-3.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":53,"sourceCodeEnd":83,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-storage/elasticsearch/src/main/java/zipkin2/elasticsearch/OpensearchSpecificTemplates.java#L53-L83","documentation":"OpensearchSpecificTemplates.get(version) builds index templates for OpenSearch and only supports 1.x through 3.x: any version below 1.0.0 or 4.0.0 and above is rejected with IllegalArgumentException. The version compared comes from cluster auto-detection (or explicit configuration) with distribution opensearch.","triggerScenarios":"Zipkin connects with distribution=opensearch to an OpenSearch 4.x+ node (or a fork reporting version >= 4), or the version string was parsed into an out-of-range OpensearchVersion; ensureIndexTemplatesOrFail() then reaches this guard and throws.","commonSituations":"Upgrading the OpenSearch cluster ahead of the bundled Zipkin build; serverless offerings that report different version numbers; misconfigured ES_VERSION forcing an out-of-range value.","solutions":["Upgrade zipkin-server / zipkin-storage-elasticsearch to a release that supports your OpenSearch version.","Or keep the cluster on OpenSearch 1-3.x.","Remove any explicit ES_VERSION override so auto-detection picks the right value, and confirm with curl GET / what the cluster reports.","If you must run 4.x now, patch OpensearchSpecificTemplates bounds and test template installation manually (PUT _index_template) before relying on it."],"exampleFix":"# before\nSTORAGE_TYPE=elasticsearch OPENSEARCH=true ES_HOSTS=http://os4:9200\n# cluster reports {\"version\":{\"number\":\"4.0.0\",\"distribution\":\"opensearch\"}}\n# -> IllegalArgumentException: OpenSearch versions 1-3.x are supported, was: 4.0.0\n\n# after: use a zipkin build with OpenSearch 4 support, or pin cluster to 3.x","handlingStrategy":"validation","validationCode":"int major = Integer.parseInt(opensearchVersionNumber.split(\"\\\\.\")[0]);\nif (major < 1 || major > 3) {\n  throw new IllegalStateException(\"Upgrade zipkin-server: this build supports OpenSearch 1-3.x, cluster is \"\n      + opensearchVersionNumber);\n}","typeGuard":null,"tryCatchPattern":"try {\n  storage.ensureIndexTemplatesOrFail();\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"OpenSearch versions 1-3.x are supported\")) {\n    // pin cluster to 3.x or upgrade zipkin — surface as deployment config error\n  }\n  throw e;\n}","preventionTips":["Check the supported OpenSearch matrix in the zipkin-server release notes before cluster upgrades.","Include a GET / version assertion in deployment smoke tests.","Do not force ES_VERSION beyond the build's advertised range."],"tags":["opensearch","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"}