could not parse schedule invalid year times - 如何解决此 Elasticsearch 异常 | Easysearch | 分布式搜索引擎

适用版本： 6.8-8.9

1. 错误异常的基本描述 #

could not parse [yearly] schedule. invalid year times 是 Elasticsearch Watcher 在解析 yearly 类型 schedule（年度调度）时抛出的异常。此错误表示 Watcher 已经识别出 yearly 调度类型，但其中的年度触发时间对象无法被 YearTimes.parse 正确解析。

常见现象 #

创建或更新 watch 时返回 HTTP 400 错误。
报错信息明确指出是 yearly schedule 的 times 无效。
常见于手动编写 yearly schedule 配置时，或在使用模板生成配置时。
如果月份值非法（如 13）、日期值非法（如 32）或时间格式错误（如 25:00），就会触发此错误。

典型报错与异常栈 #

{
  "error": {
    "root_cause": [
      {
        "type": "parse_exception",
        "reason": "could not parse [yearly] schedule. invalid year times"
      }
    ],
    "type": "parse_exception",
    "reason": "could not parse [yearly] schedule. invalid year times"
  },
  "status": 400
}

服务端日志中可能出现类似以下内容：

[2024-01-15T10:30:00,123][WARN ][o.e.x.w.t.s.YearlySchedule] [node-1] failed to parse yearly schedule
ElasticsearchParseException[could not parse [yearly] schedule. invalid year times]
    at org.elasticsearch.xpack.watcher.trigger.schedule.YearlySchedule.parse(YearlySchedule.java:89)
    at org.elasticsearch.xpack.watcher.trigger.schedule.Schedule.parse(Schedule.java:123)
Caused by: ElasticsearchParseException[could not parse year times. expected an object; but found [VALUE_STRING]]

2. 为什么会发生这个错误 #

Watcher 的 YearlySchedule.parse 方法只是一个包装层，真正的解析发生在 YearTimes.parse。因此这个异常的真实含义通常是：

月份字段不合法：月份值必须在 1-12 之间，如 0、13 都是非法的。
月内日期字段不合法：日期值必须在 1-31 之间（取决于月份），如 0、32 都是非法的。
时间字段格式错误：time 字段必须是 HH:MM 格式（24小时制），如 25:00、ab:cd 都是非法的。
数组里的某个 yearly 对象结构不完整：如果 yearly 是数组，其中某个元素解析失败就会导致整个解析失败。
字段放错位置：混入了 weekly 或 monthly 的配置字段。
模板渲染问题：使用 Mustache 或 script 模板时，渲染结果可能格式不正确。

3. 如何排查和解决这个异常和解决这个异常 #

排查步骤 #

检查 trigger.schedule.yearly 的每个对象：确认是对象还是数组。
分别核对月份、日期、时间字段：

# 获取 watch 配置
GET _watcher/watch/<watch_id>?pretty

# 检查 trigger 部分的 yearly schedule

验证年份时间字段的合法性：

# 正确的 yearly schedule 格式示例
PUT _watcher/watch/<watch_id>
{
  "trigger": {
    "schedule": {
      "yearly": {
        "in": ["JAN", "JUL"],
        "on": [1, 15],
        "at": ["12:00", "18:00"]
      }
    }
  },
  ...
}

合法的字段值：

in：月份，必须是 JAN、FEB、MAR、APR、MAY、JUN、JUL、AUG、SEP、OCT、NOV、DEC 之一
on：日期，必须是 1-31 之间的整数
at：时间，必须是 HH:MM 格式（24小时制）

如果是数组，逐个去掉元素定位问题项：

# yearly 也可以是数组
PUT _watcher/watch/<watch_id>
{
  "trigger": {
    "schedule": {
      "yearly": [
        {"in": ["JAN"], "on": [1], "at": ["12:00"]},
        {"in": ["JUL"], "on": [15], "at": ["18:00"]}
      ]
    }
  }
}

排查时需要注意的问题 #

注意月份值必须是大写的月份缩写（JAN、FEB 等），不能是数字或其他格式。
日期值必须在 1-31 范围内，且要考虑月份的天数限制（如二月最多 29 天）。
时间格式必须是 HH:MM，且小时在 0-23 范围内，分钟在 0-59 范围内。
如果使用模板变量，确保变量渲染后是合法的值。

4. 如何解决这个错误 #

常用修复方式 #

修正 yearly 子对象里的月份、日期和时间值：

# 修复前（错误：月份值非法）
PUT _watcher/watch/<watch_id>
{
  "trigger": {
    "schedule": {
      "yearly": {
        "in": ["INVALID"],  # 错误：应该是 JAN-DEC
        "on": [1],
        "at": ["12:00"]
      }
    }
  }
}

# 修复后（正确：使用合法的月份值）
PUT _watcher/watch/<watch_id>
{
  "trigger": {
    "schedule": {
      "yearly": {
        "in": ["JAN", "JUL"],
        "on": [1, 15],
        "at": ["12:00", "18:00"]
      }
    }
  }
}

清理空对象、错误数组元素和混用字段：

# 错误：包含了 monthly 的字段
"yearly": {
  "in": ["JAN"],
  "on": [1],
  "at": ["12:00"],
  "day": 1  # 错误：这是 monthly 的字段
}

# 正确：只包含 yearly 支持的字段
"yearly": {
  "in": ["JAN", "JUL"],
  "on": [1, 15],
  "at": ["12:00", "18:00"]
}

对 yearly 配置做结构化校验，而不是只做字符串拼接。

后续注意事项与推荐建议 #

在编写 yearly schedule 配置时，严格参照官方文档中的示例。
对动态生成的配置进行格式验证，确保月份、日期和时间格式合法。
在测试环境验证 schedule 配置，特别是在使用模板或程序生成配置时。

借助 INFINI 产品提升排障效率 #

INFINI Console 提供可视化的 Watch 编辑和验证功能，可以在保存前检查 yearly schedule 配置的合法性，自动检测非法的月份值、日期和时间格式。
INFINI Gateway 可以记录 Watcher API 的完整请求内容，帮助捕获 schedule 配置的详细错误上下文，并通过流量回放验证修复方案。
通过 INFINI Console 的 Watch 测试功能，可以在不执行完整 Watch 的情况下验证 schedule 配置的合法性。

5. 小结 #

could not parse [yearly] schedule. invalid year times 是一个年度时间定义错误，表示 yearly schedule 内部的某一项年度时间定义无法被 YearTimes.parse 接受。解决此问题的关键是：确保月份值是合法的大写月份缩写（JAN、FEB 等），日期值在 1-31 范围内，时间格式是 HH:MM，且字段结构正确。

通过 INFINI Console 的配置验证功能和 INFINI Gateway 的请求捕获能力，可以更高效地定位和修复 yearly schedule 的配置问题。

参考文档 #

附：日志上下文 #

下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：

public YearlySchedule parse(XContentParser parser) throws IOException {
    if (parser.currentToken() == XContentParser.Token.START_OBJECT) {
        try {
            return new YearlySchedule(YearTimes.parse(parser, parser.currentToken()));
        } catch (ElasticsearchParseException pe) {
            throw new ElasticsearchParseException("could not parse [{}] schedule. invalid year times", pe, TYPE);
        }
    }
    if (parser.currentToken() == XContentParser.Token.START_ARRAY) {
        List<YearTimes> times = new ArrayList<>();
        XContentParser.Token token;

标签

could not parse schedule invalid year times - 如何解决此 Elasticsearch 异常