What causes "[date_range] range value from parse err %s" in zincsearch/zincsearch?

Supply from values matching the effective format (default RFC3339, e.g. "2024-01-01T00:00:00Z")

zincsearch/zincsearch · error · errors.Error

illegal_argument_exception

illegal_argument_exception

Error message

[date_range] range value from parse err %s

What it means

Each date_range "from" value is parsed with time.ParseInLocation using the resolved format (field format, agg format, or RFC3339). An unparsable from string yields an illegal_argument_exception wrapping the underlying time-parse error.

Source

Thrown at pkg/uquery/aggregation/aggregation.go:132

				format = agg.DateRange.Format
			}
			timeZone := time.UTC
			if agg.DateRange.TimeZone != "" {
				timeZone, err = zutils.ParseTimeZone(agg.DateRange.TimeZone)
				if err != nil {
					return errors.New(errors.ErrorTypeXContentParseException, fmt.Sprintf("[date_range] time_zone parse err %s", err.Error()))
				}
			}
			switch prop.Type {
			case "date", "time":
				subreq = aggregations.DateRanges(search.Field(agg.DateRange.Field))
				for _, v := range agg.DateRange.Ranges {
					from := time.Time{}
					to := time.Time{}
					if v.From != "" {
						from, err = time.ParseInLocation(format, v.From, timeZone)
						if err != nil {
							return errors.New(errors.ErrorTypeIllegalArgumentException, fmt.Sprintf("[date_range] range value from parse err %s", err.Error()))
						}
					}
					if v.To != "" {
						to, err = time.ParseInLocation(format, v.To, timeZone)
						if err != nil {
							return errors.New(errors.ErrorTypeIllegalArgumentException, fmt.Sprintf("[date_range] range value to parse err %s", err.Error()))
						}
					}
					subreq.AddRange(aggregations.NewDateRange(from, to))
				}
				req.AddAggregation(name, subreq)
			default:
				return errors.New(errors.ErrorTypeParsingException, "[date_range] aggregation only support type datetime")
			}
		case agg.Histogram != nil:
			if agg.Histogram.Size == 0 {
				agg.Histogram.Size = config.Global.AggregationTermsSize
			}

View on GitHub (pinned to dd2f8afd65)

Solutions

Supply from values matching the effective format (default RFC3339, e.g. "2024-01-01T00:00:00Z")
Set an explicit "format" on the date_range agg matching your input values
Use the field's mapped format and send values in that layout

Example fix

// before
{"date_range":{"field":"@timestamp","ranges":[{"from":"2024-01-01"}]}}
// after
{"date_range":{"field":"@timestamp","ranges":[{"from":"2024-01-01T00:00:00Z"}]}}

Defensive patterns

Strategy: validation

Validate before calling

const fmt = agg.format ?? 'YYYY-MM-DDTHH:mm:ssZ'; // RFC3339 default
for (const r of ranges) {
  if (r.from && Number.isNaN(Date.parse(r.from))) {
    throw new Error(`date_range 'from' not RFC3339-parseable: ${r.from}`);
  }
}

Type guard

function isParseableDate(s) {
  return typeof s === 'string' && !Number.isNaN(Date.parse(s));
}

Try / catch

try {
  return await search(query);
} catch (e) {
  if (e.code === 'illegal_argument_exception' && e.message.includes('range value from parse err')) {
    console.error('from bound does not match expected date format; use RFC3339 or set format');
  }
  throw e;
}

Prevention

Emit all range bounds in RFC3339 (e.g. new Date().toISOString())
Set an explicit format on the aggregation matching your input layout
Avoid epoch-millis strings unless the format accepts them
Validate bounds with Date.parse before sending

When it happens

Trigger: date_range ranges entry with from set to a string that doesn't match the effective format — e.g. "2024/01/01" when the format is RFC3339, or epoch-millis numbers as strings when format expects a date layout.

Common situations: Sending epoch timestamps while the format is a date layout; dates without timezone info against RFC3339; mismatch between the field's declared format and the values supplied; locale-formatted dates.

Related errors

AI-assisted analysis of zincsearch/zincsearch@dd2f8afd65 (2026-09-03). Data as JSON: /api/errors/4d07d4792c62f712. Report an issue: GitHub.