---
title: "failed to parse hipchat message, unexpected field - 解析 HipChat 消息失败：出现意外字段"
date: 2026-03-09
lastmod: 2026-03-09
description: "failed to parse hipchat message, unexpected field 表示 Elasticsearch Watcher 在解析 HipChat 消息时发现不被支持的字段，通常是消息结构中包含了额外字段或字段名错误导致，本文详解排查与修复方法。"
tags: ["Elasticsearch", "Watcher", "HipChat", "hipchat message", "unexpected field", "parse", "通知消息", "ElasticsearchParseException"]
summary: "适用版本： 6.8-6.8（HipChat 功能在更高版本中已废弃或移除）
 1. 错误异常的基本描述 #  failed to parse hipchat message. unexpected field [{}] 表示 Elasticsearch Watcher 在解析 HipChat 消息时，发现了消息对象中包含解析器未定义的字段名，于是直接抛出 ElasticsearchParseException。从源码片段可以看出，HipChat message 只接受一组固定字段，只要对象里出现解析器未定义的键名，就会走这个分支。
这不是字段值错误，而是消息结构错误，字段名不被识别。
常见现象 #   配置 HipChat 通知的 Watcher 时返回 400 Bad Request，提示 unexpected field。 在创建或更新 Watcher 时，HipChat message 部分解析失败。 错误集中在特定 HipChat 消息配置上，其他通知渠道（如 email、slack）可能正常。 Elasticsearch 日志中可以看到 failed to parse hipchat message. unexpected field [field_name] 关键字，伴随 ElasticsearchParseException。 在 Kibana 的 Watcher 管理界面中，可能无法保存包含 HipChat 通知的 Watcher。  典型报错与异常栈 #  常见日志形态通常类似下面这样："
---


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

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

`failed to parse hipchat message. unexpected field [{}]` 表示 Elasticsearch Watcher 在解析 HipChat 消息时，发现了消息对象中包含解析器未定义的字段名，于是直接抛出 `ElasticsearchParseException`。从源码片段可以看出，HipChat message 只接受一组固定字段，只要对象里出现解析器未定义的键名，就会走这个分支。

这不是字段值错误，而是**消息结构错误**，字段名不被识别。

### 常见现象

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

### 典型报错与异常栈

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

```text
ElasticsearchParseException: failed to parse hipchat message. unexpected field [color]
	at org.elasticsearch.xpack.watcher.hipchat.HipChatMessage...
```

或者字段名拼写错误：

```text
ElasticsearchParseException: failed to parse hipchat message. unexpected field [boday]
	at org.elasticsearch.xpack.watcher.hipchat.HipChatMessage...
```

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

`failed to parse hipchat message. unexpected field [{}]` 的根因是"HipChat 消息对象中包含了不被支持的字段"。Elasticsearch Watcher 的 HipChat 通知功能对消息结构有严格限制，只允许特定字段；如果消息中包含了其他字段，就会抛出此异常。

常见原因通常包括：

- **手工添加了不受支持的字段**：在 HipChat 消息中添加了 HipChat API 可能支持但 Elasticsearch Watcher 不支持的字段。
- **把其他通知渠道字段复制到 HipChat message**：如把 Slack、Email 或其他通知渠道的字段错误复制到了 HipChat 消息中。
- **模板生成了额外层级或拼错了字段名**：模板渲染后产生了错误字段或多余层级。
- **字段名拼写错误**：如 `boday` 代替 `body`，`form` 代替 `from` 等。
- **版本不兼容**：使用了旧版本或其他通知渠道的消息模板。
- **自动注入字段**：上游系统或中间层 DTO 自动附加了业务字段到消息对象。

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

建议按"先查看报错字段、再对照官方文档、后检查消息结构"的顺序处理：

1. **查看报错中的字段名**：异常信息中的 `field_name` 就是导致失败的字段，记录下来。

   ```bash
   # 查看 Elasticsearch 日志中的具体错误信息
   grep -r "failed to parse hipchat message. unexpected field" /var/log/elasticsearch/
   ```

2. **对照官方文档**：确认当前 Elasticsearch 版本支持的 HipChat 消息字段集合。

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

   HipChat 消息支持的字段（以 6.8 为例）：
   - `body`（消息正文，必需）
   - `room`（房间 ID 或名称）
   - `notify`（是否通知所有成员，布尔值）
   - `color`（消息颜色，如 `green`、`yellow`、`red`）
   - `message_format`（消息格式，如 `text` 或 `html`）
   - `from`（发送者名称）
   - `message_format`（已废弃，使用 `format`）
   - `attachments`（附件，数组）

3. **检查消息结构**：确认是否夹带了其他通知渠道的字段或拼写错误字段。

   ```json
   // 正确的 HipChat 消息结构示例
   {
     "body": "Alert: Index health check failed",
     "room": "alerts",
     "notify": true,
     "color": "red",
     "from": "Elasticsearch Watcher"
   }
   
   // 错误示例（包含 Slack 字段）
   {
     "body": "Alert: Index health check failed",
     "channel": "#alerts",  // 错误：这是 Slack 的字段
     "username": "watcher"  // 错误：这也是 Slack 的字段
   }
   ```

4. **检查模板渲染**：如果使用模板生成消息，确认渲染后没有额外字段。

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

5. **检查上游系统**：如果消息来自上游系统，确认没有自动附加额外字段。

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

- 这个错误是消息结构问题，不是通知发送问题，需要重点关注 HipChat 消息的字段名，而不是网络或认证配置。
- HipChat 功能在 Elasticsearch 7.x 中已废弃，在 8.x 中已移除，如果计划升级，需要考虑迁移到其他通知渠道（如 Slack、Webhook）。
- 不同通知渠道（Slack、Email、HipChat）的消息结构不同，不要混用字段。

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

### 常用修复思路

- **删除不被支持的字段**：只保留 HipChat 消息允许的字段。

   ```json
   // 错误示例（包含不被支持的字段）
   {
     "body": "Alert message",
     "room": "alerts",
     "color": "red",
     "priority": "high",  // 错误：HipChat 不支持 priority 字段
     "extra_field": "value"  // 错误：额外字段
   }
   
   // 正确示例
   {
     "body": "Alert message",
     "room": "alerts",
     "notify": true,
     "color": "red"
   }
   ```

- **修正字段名拼写**：确保字段名正确，使用 HipChat 支持的字段名。

   ```json
   // 错误示例（拼写错误）
   {
     "boday": "Alert message",  // 错误：应该是 body
     "rom": "watcher"  // 错误：应该是 from
   }
   
   // 正确示例
   {
     "body": "Alert message",
     "from": "watcher"
   }
   ```

- **使用正确的通知渠道消息结构**：不要把其他渠道的字段复制到 HipChat。

   ```json
   // Slack 消息结构（不要复制到 HipChat）
   {
     "channel": "#alerts",  // Slack 字段
     "username": "watcher",  // Slack 字段
     "text": "Alert message"  // Slack 字段（不是 body）
   }
   ```

- **为消息结构增加校验**：在发送到 Elasticsearch 之前，验证消息结构只包含支持的字段。

   ```java
   // 在发送前验证字段
   Set<String> allowedFields = Set.of("body", "room", "notify", "color", "from", "message_format", "attachments");
   // 检查消息对象中的字段是否都在允许集合中
   ```

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

   ```json
   // 迁移到 Webhook 通知（示例）
   {
     "trigger": { ... },
     "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. 小结

`failed to parse hipchat message. unexpected field [{}]` 本质是一个严格的消息结构校验错误。修复重点是消息字段白名单和类型，而不是索引、节点或网络问题。大多数情况下，这个问题可以通过删除不被支持的字段、修正字段名和确保使用正确的通知渠道结构来解决。

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

## 相关错误

- [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/)
- [failed-to-parse-hipchat-message-missing-required-field-how-to-solve-this-elasticsearch-exception](/knowledge-base/elasticsearch_error/failed-to-parse-hipchat-message-missing-required-field-how-to-solve-this-elasticsearch-exception/)
- [failed-to-parse-hipchat-message-failed-to-parse-field-expected-a-how-to-solve-this-elasticsearch-exception](/knowledge-base/elasticsearch_error/failed-to-parse-hipchat-message-failed-to-parse-field-expected-a-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/)

## 参考文档

- [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
} catch (IllegalArgumentException ilae) {
    throw new ElasticsearchParseException("failed to parse hipchat message. failed to parse [" + Field.FORMAT.getPreferredName() + "] field", ilae);
}
} else {
    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 + "] field");
```