SigNoz/signoz · error · error

start time is required for search queries

Error message

start time is required for search queries

What it means

ErrStartTimeRequired is a sentinel error enforcing that search queries against ClickHouse must include a start time; without it, unbounded scans would be run.

Source

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

	signozTSTableNameV4Reduced = "distributed_time_series_v4_reduced"

	signozTableAttributesMetadata      = "distributed_attributes_metadata"
	signozLocalTableAttributesMetadata = "attributes_metadata"

	signozUpdatedMetricsMetadataLocalTable = "updated_metadata"
	signozUpdatedMetricsMetadataTable      = "distributed_updated_metadata"
	minTimespanForProgressiveSearch        = time.Hour
	minTimespanForProgressiveSearchMargin  = time.Minute
	maxProgressiveSteps                    = 4
	charset                                = "abcdefghijklmnopqrstuvwxyz" +
		"ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
	NANOSECOND = 1000000000
)

var (
	ErrNoOperationsTable            = errors.New("no operations table supplied")
	ErrNoIndexTable                 = errors.New("no index table supplied")
	ErrStartTimeRequired            = errors.New("start time is required for search queries")
	seededRand           *rand.Rand = rand.New(
		rand.NewSource(time.Now().UnixNano()))
)

// SpanWriter for reading spans from ClickHouse
type ClickHouseReader struct {
	db                      clickhouse.Conn
	prometheus              prometheus.Prometheus
	sqlDB                   sqlstore.SQLStore
	TraceDB                 string
	operationsTable         string
	durationTable           string
	indexTable              string
	errorTable              string
	usageExplorerTable      string
	SpansTable              string
	spanAttributeTableV2    string
	spanAttributesKeysTable string

View on GitHub (pinned to 5069bf80b0)

Solutions

  1. Add start (and typically end) timestamp parameters to the query string (Unix microseconds)
  2. Default the dashboard/client to a relative window like now-1h when no start is set
  3. Validate params client-side before calling the search API

Example fix

// before
GET /api/v1/search?query=error
// after
GET /api/v1/search?query=error&startTimestamp=1750000000000000&endTimestamp=1750003600000000
Defensive patterns

Strategy: validation

Validate before calling

if params.StartTimestamp == 0 {
    params.StartTimestamp = time.Now().Add(-time.Hour).UnixMicro()
}

Try / catch

err := reader.Search(ctx, params)
if errors.Is(err, clickhouseReader.ErrStartTimeRequired) {
    params.Start = defaultStart(); err = reader.Search(ctx, params)
}

Prevention

When it happens

Trigger: Calling reader search methods (span/trace search helpers) with params whose StartTimestamp/start is zero/empty; parse helpers propagate it from missing start/end params in the HTTP query.

Common situations: Clients omitting the startTimestamp query parameter; dashboards with relative-time variables that evaluate to empty; API scripts copying examples without time params.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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