What causes "invalid version %q: expected one of es7, es8, es9, os1, os2, os3" in jaegertracing/jaeger?

Set the version string to one of: es7, es8, es9, os1, os2, os3 (or a plain supported major number like 7, 8, 9, 101, 102, 103 if the parser accepts numerics).

jaegertracing/jaeger · error

invalid version %q: expected one of es7, es8, es9, os1, os2,

Error message

invalid version %q: expected one of es7, es8, es9, os1, os2, os3

What it means

ParseBackendVersion validates a user-supplied version string and fails when it doesn't map to a supported backend version (es7/es8/es9/os1/os2/os3). It is a pure input-validation error: the provided string was neither parseable as a numeric major version nor a recognized prefix.

Source

Thrown at internal/storage/elasticsearch/backend_version.go:73

	lower := strings.ToLower(s)
	if len(lower) > 2 {
		prefix, digits := lower[:2], lower[2:]
		if major, err := strconv.Atoi(digits); err == nil {
			var v BackendVersion
			switch prefix {
			case "es":
				v = BackendVersion(major)
			case "os":
				v = BackendVersion(100 + major)
			default:
				v = 0
			}
			if v != 0 && IsSupportedVersion(uint(v)) {
				return v, nil
			}
		}
	}
	return 0, fmt.Errorf("invalid version %q: expected one of es7, es8, es9, os1, os2, os3", s)
}

func (v BackendVersion) String() string {
	switch v {
	case ElasticV7:
		return "Elasticsearch 7.x"
	case ElasticV8:
		return "Elasticsearch 8.x"
	case ElasticV9:
		return "Elasticsearch 9.x"
	case OpenSearch1:
		return "OpenSearch 1.x"
	case OpenSearch2:
		return "OpenSearch 2.x"
	case OpenSearch3:
		return "OpenSearch 3.x"
	default:
		return fmt.Sprintf("Unknown(%d)", v)

View on GitHub (pinned to 806f444784)

Solutions

Set the version string to one of: es7, es8, es9, os1, os2, os3 (or a plain supported major number like 7, 8, 9, 101, 102, 103 if the parser accepts numerics).
Use 0/auto-detect instead of an explicit version when the backend is reachable.
Verify the env var/flag feeding this value is actually populated and not empty in the runtime environment.
Upgrade your Elasticsearch/OpenSearch cluster to a supported major version if running an older one.
Check the release notes for newly dropped/added supported versions after upgrading Jaeger.

Example fix

// before
v, err := es.ParseBackendVersion(os.Getenv("ES_VERSION")) // "ES7" -> error
// after
ver := strings.ToLower(strings.TrimSpace(os.Getenv("ES_VERSION")))
if ver == "" {
    ver = "0" // auto-detect
}
v, err := es.ParseBackendVersion(ver)

Defensive patterns

Strategy: validation

Validate before calling

func validBackendVersion(s string) bool {
    switch strings.ToLower(strings.TrimSpace(s)) {
    case "", "0", "es7", "es8", "es9", "os1", "os2", "os3", "7", "8", "9", "101", "102", "103":
        return true
    }
    return false
}
// call before ParseBackendVersion / before setting the env var

Try / catch

v, err := es.ParseBackendVersion(raw)
if err != nil {
    return fmt.Errorf("%v: supported values are es7, es8, es9, os1, os2, os3 (or 0 to auto-detect)", err)
}

Prevention

Prefer Version=0 (auto-detect) unless you have a reason to pin.
Whitelist-validate any env var that feeds version parsing.
Keep a lookup table of supported versions next to your deployment config.
Re-check supported versions after every Jaeger upgrade.

When it happens

Trigger: Passing a string like "6", "es6", "opensearch", "7.x", or "" to ParseBackendVersion; empty or whitespace-only input; supplying an Elasticsearch/OpenSearch major that Jaeger no longer supports (e.g. ES 6.x).

Common situations: Upgrading Jaeger while still running Elasticsearch 6; typos like 'ES7' (case/prefix mismatch); wiring an env var that is empty in the container; copying a version flag from an old deployment.

Related errors

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