---
title: "failed to parse hipchat message, missing required field - 解析 HipChat 消息失败：缺少必需字段"
date: 2026-03-10
lastmod: 2026-03-10
description: "failed to parse hipchat message, missing required field 表示 Elasticsearch Watcher 在解析 HipChat 消息时缺少必需字段（通常是 body），本文详解排查与修复方法。"
tags: ["Elasticsearch", "Watcher", "HipChat", "hipchat message", "missing field", "parse", "通知消息", "ElasticsearchParseException", "body"]
summary: "适用版本： 6.8-6.8（HipChat 功能在更高版本中已废弃或移除）
 1. 错误异常的基本描述 #  这个异常说明 HipChat message 的必填字段没有提供。根据附带源码，最典型的是 body 为空，解析器在读完整个消息对象后会直接拒绝。
典型报错：
failed to parse hipchat message. missing required [body] field 从源码中可以看到，在所有字段解析结束后检查 body：
if (body == null) { throw new ElasticsearchParseException("failed to parse hipchat message. missing required [" + Field.BODY.getPreferredName() + "] field"); } 这不是字段类型错误，而是消息结构不完整，缺少必需字段。
常见现象 #   配置 HipChat 通知的 Watcher 时返回 400 Bad Request，提示 missing required field。 在创建或更新 Watcher 时，HipChat message 部分解析失败。 错误集中在特定 HipChat 消息配置上，其他通知渠道（如 email、slack）可能正常。 Elasticsearch 日志中可以看到 failed to parse hipchat message."
---


> **适用版本：** 6.8-6.8（HipChat 功能在更高版本中已废弃或移除）

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

这个异常说明 HipChat message 的必填字段没有提供。根据附带源码，最典型的是 `body` 为空，解析器在读完整个消息对象后会直接拒绝。

典型报错：
```text
failed to parse hipchat message. missing required [body] field
```

从源码中可以看到，在所有字段解析结束后检查 `body`：
```java
if (body == null) {
    throw new ElasticsearchParseException("failed to parse hipchat message. missing required [" + Field.BODY.getPreferredName() + "] field");
}
```

这不是字段类型错误，而是**消息结构不完整**，缺少必需字段。

### 常见现象

- 配置 HipChat 通知的 Watcher 时返回 `400 Bad Request`，提示 missing required field。
- 在创建或更新 Watcher 时，HipChat message 部分解析失败。
- 错误集中在特定 HipChat 消息配置上，其他通知渠道（如 email、slack）可能正常。
- Elasticsearch 日志中可以看到 `failed to parse hipchat message. missing required [...]` 关键字，伴随 `ElasticsearchParseException`。
- 在 Kibana 的 Watcher 管理界面中，可能无法保存包含 HipChat 通知的 Watcher。

### 典型报错与异常栈

常见日志形态通常类似下面这样：

```text
ElasticsearchParseException: failed to parse hipchat message. missing required [body] field
	at org.elasticsearch.xpack.watcher.hipchat.HipChatMessage...
```

或者 room 字段缺失：

```text
ElasticsearchParseException: failed to parse hipchat message. missing required [room] field
	at org.elasticsearch.xpack.watcher.hipchat.HipChatMessage...
```

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

`failed to parse hipchat message. missing required [...]` 的根因是"HipChat 消息缺少必需字段"。Elasticsearch Watcher 的 HipChat 通知功能对消息结构有严格要求，必需字段（如 `body`、`room`）必须提供；如果缺失，就会抛出此异常。

常见原因通常包括：

- **消息里完全没有 `body`**：HipChat 消息要求必须包含 `body`（消息正文），如果缺失就会失败。
- **`body` 被条件模板裁掉了**：在模板渲染后，`body` 字段可能因为条件判断被移除或变成了空值。
- **上游只配置了 room/user 等路由字段，没有正文**：只配置了发送目标，但忘记添加消息内容。
- **消息由程序拼装**：在合并默认值时丢掉了正文，或者条件逻辑错误导致 `body` 未被设置。
- **模板渲染后变成空值**：如果 `body` 来自模板变量，变量可能未被正确替换，导致字段值为空。
- **版本不兼容**：使用了旧版本的 HipChat 消息模板，在新版本中可能字段要求有变化。

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

建议按"先检查消息结构、再确认必需字段、后检查模板渲染"的顺序处理：

1. **检查 HipChat message 最终 JSON 是否包含必需字段**：确认 `body`、`room` 等字段是否存在。

   ```bash
   # 查看 Watcher 配置
   curl -X GET "localhost:9200/_watcher/watch/my_watch" -u elastic:password | grep -A 20 "hipchat"
   ```

   HipChat 消息必需字段：
   - `body`（消息正文，必需）
   - `room`（房间 ID 或名称，必需）
   - 可选字段：`from`、`color`、`notify`、`message_format`、`attachments`

2. **如果 `body` 来自模板，确认模板渲染后没有变成空值**：

   ```json
   // 正确的 HipChat 消息结构示例
   {
     "hipchat": {
       "message": {
         "body": "Watch triggered: Index health check failed",
         "room": "alerts",
         "notify": true,
         "color": "red"
       }
     }
   }
   
   // 错误示例（缺少 body）
   {
     "hipchat": {
       "message": {
         "room": "alerts",
         "notify": true
       }
     }
   }
   ```

3. **若消息由程序拼装，确认没有在合并默认值时丢掉正文**：

   ```java
   // 在发送前检查必需字段
   if (message.getBody() == null) {
       throw new IllegalArgumentException("HipChat message body is required");
   }
   ```

4. **检查 Watcher 配置**：确认 HipChat action 配置正确，包含所有必需字段。

   ```bash
   # 查看 Watcher 配置
   curl -X GET "localhost:9200/_watcher/watch/my_watch?pretty"
   ```

5. **检查版本兼容性**：如果计划升级，确认 HipChat 功能在当前版本中是否仍受支持（7.x 中已废弃）。

   ```bash
   # 查看当前版本
   curl -X GET "localhost:9200/?pretty"
   ```

### 排查时需要注意的问题

- 这个错误是消息结构问题，不是网络或认证问题，需要重点关注 HipChat 消息内容，而不是通知渠道配置。
- HipChat 功能在 Elasticsearch 7.x 中已废弃，在 8.x 中已移除，如果计划升级，需要考虑迁移到其他通知渠道（如 Slack、Webhook）。
- `body` 是必需字段，不能为空或缺失，必须使用非空字符串。

## 4. 如何解决这个错误

### 常用修复思路

- **为 message 补上正文**：确保 `body` 字段存在且非空。

   ```json
   // 错误示例（缺少 body）
   {
     "hipchat": {
       "message": {
         "room": "alerts"
       }
     }
   }
   
   // 正确示例
   {
     "hipchat": {
       "message": {
         "body": "Watch triggered: Index health check failed",
         "room": "alerts"
       }
     }
   }
   ```

- **确认 mapping 和字段类型**：确保 `body` 是字符串类型，且内容非空。

   ```json
   // 正确：body 是非空字符串
   "body": "Alert message"
   
   // 错误：body 是对象或空值
   "body": {}  // 错误
   "body": ""   // 错误：空字符串
   ```

- **模板输出后增加非空校验**：如果 `body` 来自模板，在渲染后检查是否为空。

   ```java
   // 在模板渲染后检查
   String renderedBody = renderTemplate(template, context);
   if (renderedBody == null || renderedBody.trim().isEmpty()) {
       throw new IllegalArgumentException("Rendered HipChat body is empty");
   }
   ```

- **设置默认值**：在 Watcher 配置中为 `body` 设置合适的默认值，避免模板变量未替换时变成空值。

   ```json
   {
     "hipchat": {
       "message": {
         "body": "{{ctx.payload.message}}",  // 如果变量为空，考虑设置默认值
         "room": "alerts"
       }
     }
   }
   ```

- **考虑迁移到其他通知渠道**：如果计划升级到 7.x 或 8.x，HipChat 功能已废弃，需要迁移到 Slack、Webhook 等渠道。

   ```json
   // 迁移到 Webhook 通知（示例）
   {
     "actions": {
       "send_webhook": {
         "webhook": {
           "scheme": "https",
           "host": "webhook.site",
           "port": 443,
           "path": "/{your_webhook_url}",
           "method": "post",
           "body": "Alert: {{ctx.payload.message}}"
         }
       }
     }
   }
   ```

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

- 在应用层对 HipChat 消息进行校验，确保必需字段都存在且非空。
- 在 CI/CD 流程中加入消息结构校验步骤，在发送前验证其正确性。
- 如果计划升级 Elasticsearch，提前规划 HipChat 迁移方案，改用其他通知渠道。
- 为 Watcher 配置错误配置专门的监控和告警，在消息解析失败时及时通知。
- 定期审查 Watcher 配置，清理不被支持的字段，避免遗留兼容性问题。

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

- [INFINI Console](https://docs.infinilabs.com/console/main/) 适合查看集群的 Watcher 配置、通知渠道状态、错误趋势和消息内容，帮助快速定位 `failed to parse hipchat message` 是字段问题、结构问题还是渠道问题，并提供可视化的 Watcher 管理和编辑功能。
- [INFINI Gateway](https://docs.infinilabs.com/gateway/main/) 可以记录所有 Watcher 相关的请求日志，帮助定位 HipChat 消息解析失败的具体环节，同时提供请求审计功能。
- 建议将 Watcher 执行状态、通知成功率和消息解析错误统一接入监控面板，结合 INFINI Console 的告警功能，在消息解析失败时及时通知管理员。

## 5. 小结

看到这个错误时，应优先检查输入格式和 mapping 设计是否匹配。只要保证 `body` 等必需字段存在且非空，问题就会消失。大多数情况下，这个问题可以通过补充必需字段、检查模板渲染和确保消息结构完整来解决。

只要把消息结构校验、模板管理和渠道迁移规划固定下来，大多数 HipChat 消息解析类异常都可以被提前拦截，也更容易通过 INFINI Console 和 INFINI Gateway 实现持续防护。

## 相关错误

- [failed-to-parse-hipchat-message-unexpected-field-how-to-solve-this-elasticsearch-exception](/knowledge-base/elasticsearch_error/failed-to-parse-hipchat-message-unexpected-field-how-to-solve-this-elasticsearch-exception/)
- [failed-to-parse-hipchat-message-failed-to-parse-field-how-to-solve-this-elasticsearch-exception](/knowledge-base/elasticsearch_error/failed-to-parse-hipchat-message-failed-to-parse-field-how-to-solve-this-elasticsearch-exception/)
- [invalid-hipchataction-type-action-for-watchid-actionid-how-to-solve-this-elasticsearch-exception](/knowledge-base/elasticsearch_error/invalid-hipchataction-type-action-for-watchid-actionid-how-to-solve-this-elasticsearch-exception/)
- [failed-to-parse-how-to-solve-this-elasticsearch-exception](/knowledge-base/elasticsearch_error/failed-to-parse-how-to-solve-this-elasticsearch-exception/)
- [watcher-exception-how-to-solve-this-elasticsearch-exception](/knowledge-base/elasticsearch_error/watcher-exception-how-to-solve-this-elasticsearch-exception/)

## 参考文档

- [Elasticsearch Watcher HipChat Action 官方文档（6.8）](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/notification-settings.html#hipchat-notification-settings)
- [Elasticsearch Watcher 官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/watcher-api.html)
- [Elasticsearch 通知渠道官方文档](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/actions.html)
- [INFINI Console 文档](https://docs.infinilabs.com/console/main/)
- [INFINI Gateway 文档](https://docs.infinilabs.com/gateway/main/)

## 附：日志上下文

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

```java
throw new ElasticsearchParseException("failed to parse hipchat message. unexpected field [" + currentFieldName + "]");
}
}  if (body == null) {
    throw new ElasticsearchParseException("failed to parse hipchat message. missing required [" + Field.BODY.getPreferredName() + "] field");
}
return new HipChatMessage.Template(body, rooms, users, from, messageFormat, color, notify);
}
```