invalid mapping type %q: please pass one of %q, %q, %q, or %

Error message

invalid mapping type %q: please pass one of %q, %q, %q, or %q as the mapping type

What it means

generateMappings validates the --mapping flag against the known Jaeger index kinds (spans, services, dependencies, sampling) by delegating to esclient.MappingTypeFromString. If the user-supplied mapping token does not match any of those names, the offline mapping generator cannot know which index template to render and returns this error listing the four accepted values. It is a CLI-input validation error, not a cluster failure.

Source

Thrown at internal/storage/elasticsearch/mappings/command.go:43

				return fmt.Errorf("error generating mappings: %w", err)
			}
			fmt.Println(result)
			return nil
		},
	}
	options.AddFlags(command)

	return command
}

// generateMappings renders the index template for the requested mapping type and
// backend version. It is an offline generator, so it renders through
// esclient.RenderIndexTemplate for an explicitly-passed version rather than a
// version resolved from a live cluster.
func generateMappings(options Options) (string, error) {
	mappingType, err := esclient.MappingTypeFromString(options.Mapping)
	if err != nil {
		return "", fmt.Errorf("invalid mapping type %q: please pass one of %q, %q, %q, or %q as the mapping type", options.Mapping, config.SpanIndexName, config.ServiceIndexName, config.DependencyIndexName, config.SamplingIndexName)
	}
	enableILM, err := strconv.ParseBool(options.UseILM)
	if err != nil {
		return "", err
	}
	indexOpts := config.IndexOptions{
		Shards:   options.Shards,
		Replicas: options.Replicas,
	}
	indices := config.Indices{
		IndexPrefix:  config.IndexPrefix(options.IndexPrefix),
		Spans:        indexOpts,
		Services:     indexOpts,
		Dependencies: indexOpts,
		Sampling:     indexOpts,
	}
	rendered, err := esclient.RenderIndexTemplate(mappingType, indices, enableILM, options.ILMPolicyName, options.Version)
	if err != nil {

View on GitHub (pinned to 806f444784)

Solutions

Set --mapping to one of: spans, services, dependencies, sampling (the config.SpanIndexName/ServiceIndexName/DependencyIndexName/SamplingIndexName values printed in the error).
Use --backend (elasticsearch/opensearch) plus a valid --mapping instead of guessing; check `--help` for the accepted list.
Fix quoting in scripts so the flag isn't receiving an empty or concatenated value.

Example fix

// before
./jaeger-es-index-cleaner --mapping span
// after
./jaeger-es-index-cleaner --mapping spans

Defensive patterns

Strategy: validation

Validate before calling

valid := map[string]bool{"spans": true, "services": true, "dependencies": true, "sampling": true}
if !valid[options.Mapping] {
  return fmt.Errorf("--mapping must be one of spans, services, dependencies, sampling; got %q", options.Mapping)
}

Type guard

func isValidMappingType(m string) bool {
  switch m {
  case config.SpanIndexName, config.ServiceIndexName, config.DependencyIndexName, config.SamplingIndexName:
    return true
  }
  return false
}

Try / catch

if err != nil {
  var invalidMapping *fmt.WrapError
  if errors.As(err, &invalidMapping) {
    fmt.Fprintf(os.Stderr, "usage: --mapping spans|services|dependencies|sampling\n")
    os.Exit(2)
  }
  return err
}

Prevention

Validate CLI flags at startup with a whitelist before calling generateMappings.
Copy flag values from the error message's accepted list rather than memory.
Keep mapping names sourced from the config constants, not string literals, in tooling.

When it happens

Trigger: Running `jaeger-remote-storage`/`jaeger-es-mapping` command with `--mapping` set to a misspelled, uppercased, or entirely unknown value (e.g. --mapping=span, --mapping=Spans, --mapping=jaeger-span) so MappingTypeFromString fails.

Common situations: Typo in deployment scripts or Helm args; copying flags from older Jaeger versions where the mapping names differed; confusing index name (jaeger-span-0001) with the mapping type (spans).

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

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