jaegertracing/jaeger · error

failed to check if alias exists: %w

Error message

failed to check if alias exists: %w

What it means

Returned by IndicesClient.AliasExists when the HEAD /_alias/<name> probe fails with anything other than a 404 ResponseError. A 404 is translated to (false, nil); every other failure (transport error, 4xx/5xx not surfaced as ResponseError, timeout) becomes this wrapped error. It means the alias-existence check itself failed, not that the alias is missing.

Source

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

		return fmt.Errorf("failed to delete aliases: %w", err)
	}
	return nil
}

// AliasExists check whether an alias exists or not
func (i *IndicesClient) AliasExists(ctx context.Context, alias string) (bool, error) {
	_, err := i.request(ctx, elasticRequest{
		endpoint: "_alias/" + alias,
		method:   http.MethodHead,
	})
	if err != nil {
		var responseError ResponseError
		if errors.As(err, &responseError) {
			if responseError.StatusCode == http.StatusNotFound {
				return false, nil
			}
		}
		return false, fmt.Errorf("failed to check if alias exists: %w", err)
	}
	return true, nil
}

// IndexExists check whether an index exists or not
func (i *IndicesClient) IndexExists(ctx context.Context, index string) (bool, error) {
	_, err := i.request(ctx, elasticRequest{
		endpoint: index,
		method:   http.MethodHead,
	})
	if err != nil {
		var responseError ResponseError
		if errors.As(err, &responseError) {
			if responseError.StatusCode == http.StatusNotFound {
				return false, nil
			}
		}
		return false, fmt.Errorf("failed to check if index exists: %w", err)

View on GitHub (pinned to 806f444784)

Solutions

1. Check ES connectivity and auth (401/403 indicate bad credentials) via curl
2. Distinguish from a clean 'alias does not exist' (which returns false, nil) before deciding to create the alias
3. Retry after verifying cluster health — this check is read-only and safe to repeat
4. Unwrap the error to inspect the underlying cause (timeout vs auth vs connection)

Example fix

// before
exists, err := client.AliasExists(ctx, "jaeger-span-write")
if err != nil { return err } // cannot tell missing vs broken
// after
exists, err := client.AliasExists(ctx, "jaeger-span-write")
if err != nil {
    var respErr esclient.ResponseError
    if errors.As(err, &respErr) && respErr.StatusCode == 401 {
        return fmt.Errorf("check ES credentials: %w", err)
    }
    return retryable(err)
}

// pre-flight auth check
resp, err := http.Get(esURL + "/_cluster/health")
if err != nil || resp.StatusCode == 401 {
    return fmt.Errorf("bad ES credentials")
}

var respErr esclient.ResponseError
isAuthProblem := func(err error) bool {
    var re esclient.ResponseError
    return errors.As(err, &re) && (re.StatusCode == 401 || re.StatusCode == 403)
}

exists, err := client.AliasExists(ctx, alias)
if err != nil {
    var respErr esclient.ResponseError
    if errors.As(err, &respErr) {
        return fmt.Errorf("alias probe rejected, status=%d", respErr.StatusCode)
    }
    return retryable(err) // transport failure: do NOT treat as 'alias missing'
}

When it happens

Trigger: HEAD _alias/<alias> fails without a 404 ResponseError: connection refused, TLS failure, timeout, or a non-404 structured error not wrapped as ResponseError (e.g. 401/403, 503).

Common situations: ES credentials missing/invalid so the HEAD returns 401; ES temporarily unavailable during Jaeger startup before it decides to create the alias; load balancer returning 503 HTML bodies that can't be parsed as ResponseError.

Related errors

• failed to create aliases: %w
• failed to delete aliases: %w
• 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/d8d3e7230d372bc3. Report an issue: GitHub.