jaegertracing/jaeger · error

failed to render mapping to string: %w

Error message

failed to render mapping to string: %w

What it means

After the mapping type is resolved, generateMappings renders the index template offline via esclient.RenderIndexTemplate for the explicitly passed --version. If that rendering fails (unsupported version, ILM policy serialization problem, etc.) the underlying error is wrapped with this message so the CLI reports which stage failed.

Source

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

	}
	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 {
		return "", fmt.Errorf("failed to render mapping to string: %w", err)
	}
	return rendered, nil
}

View on GitHub (pinned to 806f444784)

Solutions

1. Read the wrapped %w cause in the error output; it identifies the renderer failure (usually unsupported version).
2. Pass a supported version via --backend or --es-version (7, 8, 9, or OpenSearch 101-103).
3. If using ILM, ensure --ilm-policy-name names a valid policy and the embedded policy JSON renders for that version.

Example fix

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

if !es.IsSupportedVersion(uint(options.Version)) {
  return fmt.Errorf("version %d not renderable; use 7/8/9 or 101/102/103", options.Version)
}

rendered, err := generateMappings(options)
if err != nil {
  return fmt.Errorf("mapping generation failed: %w", err)
}

When it happens

Trigger: Calling generateMappings with an options.Version that RenderIndexTemplate cannot render a template for, or an ILMPolicyName/enableILM combination the renderer rejects; RenderIndexTemplate returns a non-nil error.

Common situations: Passing an --es-version outside 7/8/9 (or OpenSearch 101-103); template rendering code updated while pinned flags were not; corrupted or empty policy name with --use-ilm=true.

Related errors

• error generating mappings: %w
• file must begin with '['
• max spans count reached
• empty configuration
• at least one storage backend is required

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