max spans allowed in trace limit reached, please contact sup

Error message

max spans allowed in trace limit reached, please contact support for more details

What it means

SearchTraces refuses to return a trace whose span count (traceSummary.NumSpans) exceeds params.MaxSpansInTrace. This is a protective limit so the UI/backend does not explode rendering or fetching gigantic traces.

Source

Thrown at pkg/query-service/app/clickhouseReader/reader.go:5283

			IsSubTree: false,
			Events:    make([][]interface{}, 0),
		},
	}

	var traceSummary model.TraceSummary
	summaryQuery := fmt.Sprintf("SELECT trace_id, min(start) AS start, max(end) AS end, sum(num_spans) AS num_spans FROM %s.%s WHERE trace_id=$1 GROUP BY trace_id", r.TraceDB, r.traceSummaryTable)
	err := r.db.QueryRow(ctx, summaryQuery, params.TraceID).Scan(&traceSummary.TraceID, &traceSummary.Start, &traceSummary.End, &traceSummary.NumSpans)
	if err != nil {
		if err == sql.ErrNoRows {
			return &searchSpansResult, nil
		}
		r.logger.Error("Error in processing sql query", errorsV2.Attr(err))
		return nil, fmt.Errorf("error in processing sql query")
	}

	if traceSummary.NumSpans > uint64(params.MaxSpansInTrace) {
		r.logger.Error("Max spans allowed in a trace limit reached", "MaxSpansInTrace", params.MaxSpansInTrace, "Count", traceSummary.NumSpans)
		return nil, fmt.Errorf("max spans allowed in trace limit reached, please contact support for more details")
	}

	var startTime, endTime, durationNano uint64
	var searchScanResponses []model.SpanItemV2

	query := fmt.Sprintf("SELECT timestamp, duration_nano, span_id, trace_id, has_error, kind, resource_string_service$$name, name, links as references, attributes_string, attributes_number, attributes_bool, resources_string, events, status_message, status_code_string, kind_string FROM %s.%s WHERE trace_id=$1 and ts_bucket_start>=$2 and ts_bucket_start<=$3", r.TraceDB, r.traceTableName)
	err = r.db.Select(ctx, &searchScanResponses, query, params.TraceID, strconv.FormatInt(traceSummary.Start.Unix()-1800, 10), strconv.FormatInt(traceSummary.End.Unix(), 10))
	if err != nil {
		r.logger.Error("Error in processing sql query", errorsV2.Attr(err))
		return nil, fmt.Errorf("error in processing sql query")
	}

	searchSpansResult[0].Events = make([][]interface{}, len(searchScanResponses))

	searchSpanResponses := []model.SearchSpanResponseItem{}

	for _, item := range searchScanResponses {
		ref := []model.OtelSpanRef{}

View on GitHub (pinned to 5069bf80b0)

Solutions

Raise MaxSpansInTrace in the query-service configuration if genuinely need the full trace
Apply tail/head sampling to reduce span volume at the collector
Find and fix the service generating excessive spans (recursion, tight-loop spans, unbatched work)
View the trace summary or a filtered subset instead of the full trace

Example fix

// before
if traceSummary.NumSpans > uint64(params.MaxSpansInTrace) {
    return nil, fmt.Errorf("max spans allowed in trace limit reached, please contact support for more details")
}

// after (honour a client limit param with a clear message)
if traceSummary.NumSpans > uint64(params.MaxSpansInTrace) {
    return nil, fmt.Errorf("trace has %d spans which exceeds the maximum of %d; narrow the time range or raise MaxSpansInTrace", traceSummary.NumSpans, params.MaxSpansInTrace)
}

Defensive patterns

Strategy: validation

Validate before calling

// Fetch the summary first and check size before requesting full trace
summary, _ := getTraceSummary(traceID)
if summary.NumSpans > uint64(maxSpans) {
    return fmt.Errorf("trace too large (%d spans) to render; use sampling or summary view", summary.NumSpans)
}

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "max spans allowed in trace limit reached") {
        // show summary UI instead of failing hard
        renderTraceSummary(traceID)
        return
    }
    return err
}

Prevention

Configure collector sampling to cap spans per trace
Set MaxSpansInTrace appropriate to your UI capacity
Instrument high-span services with coarser spans

When it happens

Trigger: GET /api/v1/traces/{traceID} (SearchTraces) where the trace has more spans than MaxSpansInTrace — e.g. a trace with hundreds of thousands of spans from a hot loop, recursive service calls, or an instrumentation bug creating excessive spans.

Common situations: Microservice recursion or retry storms producing huge traces, missing sampling rules so every request is recorded, or MaxSpansInTrace set too low in query-service config.

Related errors

AI-assisted analysis of SigNoz/signoz@5069bf80b0 (2026-08-28). Data as JSON: /api/errors/7fef98d47d4ce178. Report an issue: GitHub.