SigNoz/signoz · error

error while querying histogram buckets: %s

Error message

error while querying histogram buckets: %s

What it means

Raised when the ClickHouse query that fetches histogram 'le' bucket boundaries fails. The query targets the signoz_metrics time_series table filtered by metric name, unixMilli cutoff, and service name; any ClickHouse error (syntax from bad identifiers, timeout, unavailable table) surfaces here.

Source

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

				)
				GROUP BY le
				ORDER BY le`, signozMetricDBName, signozTSTableNameV41Day, signozMetricDBName, signozTSTableNameV4Reduced)
		} else {
			query = fmt.Sprintf(`
			SELECT JSONExtractString(labels, 'le') AS le
			FROM %s.%s
			WHERE metric_name = $1
				AND unix_milli >= $2
				AND type = 'Histogram'
				AND (JSONExtractString(labels, 'service_name') = $3 OR JSONExtractString(labels, 'service.name') = $4)
			GROUP BY le
			ORDER BY le`, signozMetricDBName, signozTSTableNameV41Day)
		}

		rows, err := r.db.Query(ctx, query, metricName, unixMilli, serviceName, serviceName)
		if err != nil {
			r.logger.Error("Error while querying histogram buckets", errorsV2.Attr(err))
			return nil, fmt.Errorf("error while querying histogram buckets: %s", err.Error())
		}
		defer rows.Close()

		for rows.Next() {
			var leStr string
			if err := rows.Scan(&leStr); err != nil {
				return nil, fmt.Errorf("error while scanning le: %s", err.Error())
			}
			le, err := strconv.ParseFloat(leStr, 64)
			if err != nil || math.IsInf(le, 0) {
				r.logger.Error("Invalid 'le' bucket value", "value", leStr, errorsV2.Attr(err))
				continue
			}
			leFloat64 = append(leFloat64, le)
		}
	}

	return &v3.MetricMetadataResponse{

View on GitHub (pinned to 5069bf80b0)

Solutions

  1. Check wrapped ClickHouse error text for syntax vs timeout causes
  2. Verify the v4 time_series table exists in signoz_metrics DB (migration status)
  3. Sanitize/validate metric and service names before calling the API
  4. Increase ClickHouse query timeout or max memory limit if the error is a resource timeout

Example fix

// before
rows, err := r.db.Query(ctx, query, metricName, unixMilli, serviceName, serviceName)

// after: validate inputs to avoid query construction issues
if metricName == "" || serviceName == "" {
    return nil, model.BadRequest(fmt.Errorf("metricName and serviceName are required"))
}
rows, err := r.db.Query(ctx, query, metricName, unixMilli, serviceName, serviceName)
Defensive patterns

Strategy: retry

Validate before calling

if metricName == "" || serviceName == "" {
    return errors.New("metricName and serviceName are required")
}

Try / catch

// Retry transient ClickHouse failures
var rows *sql.Rows
for attempt := 0; attempt < 3; attempt++ {
    rows, err = r.db.Query(ctx, query, args...)
    if err == nil { break }
    time.Sleep(backoff(attempt))
}

Prevention

When it happens

Trigger: Calling GetHistogramBucketList (or equivalent) with a metric name containing special characters that break the interpolated query; when signoz_metrics.time_series_v4_1_day doesn't exist (older SigNoz schema); ClickHouse timeout or memory limit exceeded.

Common situations: Version mismatch between query-service and ClickHouse schema (v4 tables not migrated); very wide service/metric filters scanning huge partitions; ClickHouse node restart or connection pool exhaustion; metric names with quotes injected via dashboard variables.

Related errors

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