jaegertracing/jaeger · error

trace_id is required

Error message

trace_id is required

What it means

The buildQuery helper of get_span_details validates that a trace ID was supplied before building querysvc.GetTraceParams. An empty TraceID cannot be parsed into a pcommon.TraceID, so the handler returns this sentinel error immediately.

Source

Thrown at cmd/jaeger/internal/extension/jaegerquery/internal/mcptools/internal/handlers/get_span_details.go:127

	// Report any span IDs that were not found
	if len(spanIDSet) > 0 {
		missingIDs := make([]string, 0, len(spanIDSet))
		for spanID := range spanIDSet {
			missingIDs = append(missingIDs, spanID)
		}
		output.Error = fmt.Sprintf("spans not found: %v", missingIDs)
	}

	return nil, output, nil
}

// buildQuery converts GetSpanDetailsInput to querysvc.GetTraceParams and returns
// the requested span IDs in canonical lowercase hex form for the lookup set.
func (h *getSpanDetailsHandler) buildQuery(input types.GetSpanDetailsInput) (querysvc.GetTraceParams, []string, error) {
	// Validate input
	if input.TraceID == "" {
		return querysvc.GetTraceParams{}, nil, errors.New("trace_id is required")
	}

	if len(input.SpanIDs) == 0 {
		return querysvc.GetTraceParams{}, nil, errors.New("span_ids is required and must not be empty")
	}

	// Validate span count against configured limit
	if len(input.SpanIDs) > h.maxSpanDetailsPerRequest {
		return querysvc.GetTraceParams{}, nil, fmt.Errorf(
			"span_ids exceeds maximum limit: requested %d, max allowed %d",
			len(input.SpanIDs),
			h.maxSpanDetailsPerRequest,
		)
	}

	traceID, err := parseTraceID(input.TraceID)
	if err != nil {
		return querysvc.GetTraceParams{}, nil, fmt.Errorf("invalid trace_id: %w", err)

View on GitHub (pinned to 806f444784)

Solutions

1. Supply a non-empty trace_id alongside span_ids
2. Add required-field validation in the MCP client or tool input schema
3. Guard chained tool calls so a failed upstream lookup does not propagate an empty ID

Example fix

// before
req := types.GetSpanDetailsInput{SpanIDs: spanIDs}
// after
if traceID == "" {
    return errors.New("cannot call get_span_details without trace_id")
}
req := types.GetSpanDetailsInput{TraceID: traceID, SpanIDs: spanIDs}

if input.TraceID == "" {
    return errors.New("refusing to call get_span_details without trace_id")
}

out, err := handler.Handle(ctx, req, input)
if err != nil && strings.Contains(err.Error(), "trace_id is required") {
    return fmt.Errorf("get_span_details requires trace_id; got empty input")
}

When it happens

Trigger: Calling the get_span_details MCP tool with TraceID == "" while span_ids are provided; typically a client omitted the trace_id argument entirely.

Common situations: MCP tool schema lacking required-field enforcement; an orchestration step forwarding empty context; UI form submitted without selecting a trace.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• trace_id is required
• service_name is required
• trace_id is required
• start_time must be before end_time
• span_ids is required and must not be empty

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