jaegertracing/jaeger · error

unsupported --es-version %d: expected 7, 8, 9 (Elasticsearch

Error message

unsupported --es-version %d: expected 7, 8, 9 (Elasticsearch) or 101, 102, 103 (OpenSearch); prefer --backend

What it means

resolveBackendVersion maps the legacy --es-version numeric flag to a BackendVersion. When no --backend token is given and the numeric value is not one of the supported Elasticsearch (7, 8, 9) or OpenSearch (101, 102, 103) codes, the tool refuses to guess (values < 101 could otherwise be misread as OpenSearch) and returns this error, suggesting the newer --backend flag.

Source

Thrown at internal/storage/elasticsearch/mappings/flags.go:37

	Replicas      *int64
	IndexPrefix   string
	UseILM        string // using string as util is being used in python and using bool leads to type issues.
	ILMPolicyName string
}

// resolveBackendVersion selects the backend version from the generator's two
// version flags. The distribution-aware --backend token ("es8", "os3") wins when
// set; otherwise the legacy numeric --es-version is used. The legacy flag still
// accepts OpenSearch codes (101-103) for backward compatibility — --backend is
// just the readable spelling — so the number is validated against the supported
// set rather than cast blindly (an unsupported value like 999 would otherwise be
// misread as OpenSearch, since IsOpenSearch is >= 101).
func resolveBackendVersion(backendToken string, legacyEsVersion uint) (es.BackendVersion, error) {
	if backendToken != "" {
		return es.ParseBackendVersion(backendToken)
	}
	if !es.IsSupportedVersion(legacyEsVersion) {
		return 0, fmt.Errorf("unsupported --es-version %d: expected 7, 8, 9 (Elasticsearch) or 101, 102, 103 (OpenSearch); prefer --backend", legacyEsVersion)
	}
	return es.BackendVersion(legacyEsVersion), nil
}

const (
	mappingFlag       = "mapping"
	backendFlag       = "backend"
	esVersionFlag     = "es-version"
	shardsFlag        = "shards"
	replicasFlag      = "replicas"
	indexPrefixFlag   = "index-prefix"
	useILMFlag        = "use-ilm"
	ilmPolicyNameFlag = "ilm-policy-name"
)

// AddFlags adds flags for esmapping-generator main program
func (o *Options) AddFlags(command *cobra.Command) {
	command.Flags().StringVar(

View on GitHub (pinned to 806f444784)

Solutions

1. Prefer --backend=elasticsearch or --backend=opensearch and drop --es-version entirely.
2. If keeping --es-version, set it to 7, 8, or 9 for Elasticsearch or 101, 102, 103 for OpenSearch 1.x/2.x/3.x respectively.
3. Update deployment manifests/Helm values that pin the legacy flag.

Example fix

// before
--es-version=6
// after
--backend=elasticsearch --es-version=7

supported := map[uint]bool{7: true, 8: true, 9: true, 101: true, 102: true, 103: true}
if !supported[esVersion] {
  return fmt.Errorf("--es-version=%d unsupported", esVersion)
}

func isSupportedLegacyVersion(v uint) bool {
  return v == 7 || v == 8 || v == 9 || v == 101 || v == 102 || v == 103
}

bv, err := resolveBackendVersion(backend, esVersion)
if err != nil {
  log.Fatalf("bad version flags: %v — set --backend=elasticsearch|opensearch", err)
}

When it happens

Trigger: Running the mapping command with --es-version set to anything other than 7/8/9/101/102/103 — e.g. --es-version=6, --es-version=0, or --es-version=8.x — while --backend is empty.

Common situations: Migrating from Jaeger 1.x where ES 6 was supported; scripts defaulting the flag to 0; operators not realizing OpenSearch uses 101-103 codes; ES 10-style values.

Related errors

• invalid Jaeger tag pair %q, expected key=value
• invalid mapping type %q: please pass one of %q, %q, %q, or %
• trace_id is required
• start_time must be before end_time
• trace_id is required

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/4733402bebd68d6e. Report an issue: GitHub.