jaegertracing/jaeger · warning

failed to check if template exists: %w

Error message

failed to check if template exists: %w

What it means

Returned by the test-only IndicesClient.TestsOnlyTemplateExists when the HEAD request against the template endpoint (_index_template/<name> on v8, _template/<name> otherwise) fails with anything other than a 404 ResponseError. 404 means the template is absent (false, nil); any other failure yields this wrapped error. It indicates the probe failed, not that the template is missing.

Source

Thrown at internal/storage/elasticsearch/esclient/index_client.go:369

		return "_index_template/" + name
	}
	return "_template/" + name
}

// TestsOnlyTemplateExists reports whether the index template for name exists,
// using the same endpoint CreateTemplate installs it under. Integration-test-only
// — production never checks a template's existence.
func (i IndicesClient) TestsOnlyTemplateExists(ctx context.Context, name string) (bool, error) {
	_, err := i.request(ctx, elasticRequest{
		endpoint: i.templateEndpoint(name),
		method:   http.MethodHead,
	})
	if err != nil {
		var responseError ResponseError
		if errors.As(err, &responseError) && responseError.StatusCode == http.StatusNotFound {
			return false, nil
		}
		return false, fmt.Errorf("failed to check if template exists: %w", err)
	}
	return true, nil
}

// TestsOnlyDeleteTemplate deletes the index template for name (the same endpoint
// CreateTemplate installs it under), tolerating a missing template. Integration-
// test-only — production never deletes templates.
func (i IndicesClient) TestsOnlyDeleteTemplate(ctx context.Context, name string) error {
	_, err := i.request(ctx, elasticRequest{
		endpoint: i.templateEndpoint(name),
		method:   http.MethodDelete,
	})
	if err != nil {
		var responseError ResponseError
		if errors.As(err, &responseError) && responseError.StatusCode == http.StatusNotFound {
			return nil
		}
		return fmt.Errorf("failed to delete template %q: %w", name, err)

View on GitHub (pinned to 806f444784)

Solutions

1. Ensure the test ES container is healthy before running (wait for cluster health)
2. Verify the backend version detection so templateEndpoint targets the right API (_index_template vs _template)
3. Check test-user permissions for template APIs
4. Retry the check — it is read-only and safe to repeat

Example fix

// before
exists, err := client.TestsOnlyTemplateExists(ctx, "jaeger-span")
require.NoError(t, err)
// after
exists, err := client.TestsOnlyTemplateExists(ctx, "jaeger-span")
if err != nil {
    var respErr esclient.ResponseError
    if errors.As(err, &respErr) {
        t.Fatalf("template probe rejected, status=%d", respErr.StatusCode)
    }
    t.Fatalf("ES unreachable during test: %v", err)
}

// test pre-flight: wait for ES readiness before template checks
require.Eventually(t, func() bool {
    resp, err := http.Get(esURL + "/_cluster/health")
    return err == nil && resp.StatusCode == 200
}, 30*time.Second, time.Second)

var respErr esclient.ResponseError
isMissing := func(err error) bool {
    var re esclient.ResponseError
    return errors.As(err, &re) && re.StatusCode == http.StatusNotFound
}

exists, err := client.TestsOnlyTemplateExists(ctx, name)
if err != nil {
    var respErr esclient.ResponseError
    if errors.As(err, &respErr) {
        t.Fatalf("template probe rejected, status=%d", respErr.StatusCode)
    }
    t.Fatalf("ES unreachable during template probe: %v", err)
}

When it happens

Trigger: HEAD on the template endpoint fails without a 404 ResponseError: ES unreachable in the integration-test environment, auth failure (401/403), timeout, or non-JSON error responses.

Common situations: Integration tests running against a not-yet-ready ES container; wrong ES version image where the v8 vs legacy endpoint routing mismatches; test credentials/permissions blocking HEAD on _index_template.

Related errors

• failed to create template: %w
• invalid mapping type: %s
• file must begin with '['
• max spans count reached
• empty configuration

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