适用版本： 6.8-8.11
1. 错误异常的基本描述 #
failed to parse time unit 是 Elasticsearch 在解析时间字符串时抛出的底层异常，表示传入的时间值无法被正确识别为合法的 TimeValue。该错误通常出现在需要时间参数的配置中，例如 Watcher 定时任务、索引生命周期管理（ILM）、超时设置、重试间隔等场景。
Elasticsearch 内部使用 TimeValue 类统一处理时间参数，要求时间字符串必须遵循 数值 + 单位 的格式。当单位部分无法被识别时，就会触发此异常。
常见现象 #
- 创建或更新 Watcher、ILM 策略时返回
400错误，提示failed to parse time unit。 - 集群日志中出现
ElasticsearchParseException，并伴随failed to parse time unit的错误信息。 - 使用 REST API 设置超时参数（如
timeout、master_timeout）时，请求被拒绝。 - Kibana 或客户端 SDK 在调用相关接口时抛出异常，导致功能不可用。
典型报错与异常栈 #
常见日志形态通常类似下面这样：
ElasticsearchParseException: failed to parse time unit
Caused by: ElasticsearchParseException: could not parse time value [5x]. unknown time unit [x]
at org.elasticsearch.common.unit.TimeValue.parseTimeValue(TimeValue.java)
2. 为什么会发生这个错误 #
failed to parse time unit 的本质原因是时间字符串的单位部分不符合 Elasticsearch 的解析规则。Elasticsearch 只接受一组预定义的时间单位，任何不在白名单内的单位都会导致解析失败。
常见原因通常包括：
- 单位拼写错误：使用了 Elasticsearch 不支持的单位缩写，例如
5y（正确应为5y需注意版本差异）、5min（正确应为5m）、1hr（正确应为1h）。 - 大小写不匹配：虽然部分单位不区分大小写，但混用大小写仍可能导致解析失败，例如
5M在某些上下文会被解析为月份而非分钟。 - 多余字符或空格：时间字符串中混入了空格、换行符或不可见字符，例如
5 m、5m、5 m（全角空格）。 - 单位缺失：只提供了数值部分而没有单位，例如
5而不是5s。 - 使用自然语言：直接将人类可读的文本传给时间参数，例如
five minutes、5 分钟、半天。 - 模板拼接错误：在动态生成时间字符串时，数值与单位被意外拆分，或拼接逻辑引入了额外的字符。
- 版本差异：不同 Elasticsearch 版本支持的时间单位集合有所不同，低版本不支持的单位在高版本中可能可用，反之亦然。
Elasticsearch 支持的标准时间单位包括：
| 单位符号 | 含义 |
|---|---|
ms | 毫秒 |
s | 秒 |
m | 分钟 |
h | 小时 |
d | 天 |
w | 周 |
M | 月（注意大写） |
y | 年 |
3. 如何排查和解决这个异常 #
建议按以下顺序排查：
- 从报错信息或日志中找到完整的时间字符串原始值，确认报错指向的具体参数位置。
- 检查时间字符串是否符合
数值 + 单位的基本格式，数值部分应为非负整数或小数。 - 逐一核对单位部分是否在 Elasticsearch 支持的单位列表中，注意大小写和拼写。
- 检查字符串中是否存在空格、换行符、制表符或全角字符，建议使用代码或脚本打印字符串的十六进制表示。
- 如果时间字符串来自模板拼接或配置文件，检查拼接逻辑和配置来源，确认数值与单位没有被意外拆分。
- 对照 Elasticsearch 版本确认该单位是否被当前版本支持。
排查时需要注意的问题 #
- 不要只盯着一个时间参数，Watcher 或 ILM 中可能同时配置了多个时间字段，需要逐一排查。
- 如果时间值来自环境变量或外部配置中心，需要确认实际注入的值与预期一致，避免配置覆盖或格式转换带来的问题。
- 注意
m和M的区别：小写m表示分钟，大写M表示月份，两者含义完全不同。
4. 如何解决这个错误 #
常用修复思路 #
- 将时间单位替换为 Elasticsearch 标准单位，例如将
5min改为5m，将1hr改为1h，将30sec改为30s。 - 去除时间字符串中的所有空格和不可见字符，确保格式为严格的
数值+单位。 - 如果时间值来自代码拼接，建议在拼接完成后打印最终字符串进行校验，或在拼接处增加格式断言。
- 对于来自配置文件的时间参数，在加载配置时增加格式校验，提前拦截非法值并给出明确错误提示。
- 如果使用了动态模板或脚本生成时间值，检查模板语法，确保数值变量和单位字符串没有被拆开处理。
修复示例 #
错误写法：
{
"trigger": {
"schedule": {
"interval": "5 min"
}
}
}
正确写法：
{
"trigger": {
"schedule": {
"interval": "5m"
}
}
}
后续注意事项与推荐建议 #
- 在代码或配置中统一管理时间单位常量，避免散落在各处的魔法字符串导致维护困难。
- 为时间参数编写单元测试或集成测试，覆盖各种单位组合，提前发现不兼容的写法。
- 在团队内部建立时间参数书写规范，明确只使用 Elasticsearch 官方支持的单位列表。
- 如果项目中大量使用时间配置，考虑封装一个时间值校验工具函数，在应用启动或配置加载时进行预检。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合查看集群配置、索引设置、Watcher 任务状态和错误日志，帮助快速定位是哪一处配置的时间参数不合法。
- INFINI Gateway 适合部署在 Elasticsearch 前面做请求观测和流量治理，可以在请求到达 ES 之前拦截并打印异常的时间参数，便于提前发现问题。
5. 小结 #
failed to parse time unit 是一个典型的时间格式校验错误，根源几乎总是时间字符串的单位部分不符合 Elasticsearch 的解析规则。处理时只需抓住两个关键点：确认时间字符串是严格的 数值 + 单位 格式，且单位在 Elasticsearch 支持的范围内。只要统一时间单位的书写规范，并在代码或配置层面增加格式校验，这类问题可以完全避免。
相关错误 #
附：日志上下文 #
下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：
if (value.millis() < 0) {
throw new ElasticsearchParseException("could not parse time value [{}]. Time value cannot be negative.", parser.text());
}
return value;
} catch (ElasticsearchParseException epe) {
throw new ElasticsearchParseException("failed to parse time unit", epe);
}
