What causes "expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds" in larksuite/cli?

Use RFC3339 with offset: 2026-09-04T00:00:00+08:00.

expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds

Error message

expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds

What it means

toUnixSeconds parses --filter time-range values (e.g. create_time.start) and accepts RFC3339, YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, and plain unix seconds. When none of those formats (nor integer parsing) matches, it returns this message, which the caller wraps in a typed ValidationError naming the offending key and value.

Source

Thrown at shortcuts/doc/docs_search.go:263

}

func toUnixSeconds(input string) (int64, error) {
	formats := []string{
		time.RFC3339,
		"2006-01-02T15:04:05",
		"2006-01-02 15:04:05",
		"2006-01-02",
	}
	for _, f := range formats {
		if t, err := time.ParseInLocation(f, input, time.Local); err == nil {
			return t.Unix(), nil
		}
	}
	// Try as number
	if n, err := strconv.ParseInt(input, 10, 64); err == nil {
		return n, nil
	}
	return 0, fmt.Errorf("expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds") //nolint:forbidigo // intermediate parse helper; caller wraps into typed ValidationError
}

func unixTimestampToISO8601(v interface{}) string {
	if v == nil {
		return ""
	}

	var num float64
	switch val := v.(type) {
	case float64:
		num = val
	case json.Number:
		parsed, err := val.Float64()
		if err != nil {
			return ""
		}
		num = parsed
	case string:

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Use RFC3339 with offset: 2026-09-04T00:00:00+08:00.
Or use a plain date 2026-09-04 (optionally with 15:04:05 time) or bare unix seconds like 1756944000.
Compute relative ranges yourself (e.g. with date -d '-1 day' +%s) and pass the resulting unix seconds.

Example fix

// before
lark-cli doc search --filter '{"create_time":{"start":"yesterday"}}'
// after
lark-cli doc search --filter '{"create_time":{"start":"2026-09-03T00:00:00+08:00"}}'

Defensive patterns

Strategy: validation

Validate before calling

# Validate the timestamp before invoking:
date -j -f "%Y-%m-%dT%H:%M:%S%z" "2026-09-04T00:00:00+0800" "+%s" || echo "use RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds"

Type guard

func validTimeRangeValue(s string) bool {
    formats := []string{time.RFC3339, "2006-01-02", "2006-01-02 15:04:05"}
    for _, f := range formats {
        if _, err := time.ParseInLocation(f, s, time.Local); err == nil {
            return true
        }
    }
    _, err := strconv.ParseInt(s, 10, 64)
    return err == nil
}

Try / catch

// Callers should surface the typed ValidationError including the offending value:
if _, err := toUnixSeconds(v); err != nil {
    return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid %s %q: %s", key, v, err)
}

Prevention

Always use one of: RFC3339 with numeric offset, YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, or integer unix seconds.
Avoid relative expressions ('yesterday', 'now-1d') and float timestamps — compute them to unix seconds first.
Include the timezone offset explicitly; bare 'Z'-less times without offset may fail RFC3339 parsing.

When it happens

Trigger: Passing a value like '2026/09/04', '09-04-2026', 'yesterday', 'now-1d', an empty-string date part, or a float timestamp ('1756944000.5') in a filter time field.

Common situations: Copy-pasting human-formatted dates from spreadsheets or locale formats (MM/DD/YYYY); using relative time expressions that are not supported; including timezone names like 'UTC' that Go's RFC3339 parser rejects.

Related errors

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/8e18803bf6515ca3. Report an issue: GitHub.