failed to parse hipchat message, missing required field - 解析 HipChat 消息失败：缺少必需字段

适用版本： 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. missing required [...] 关键字，伴随 ElasticsearchParseException。
• 在 Kibana 的 Watcher 管理界面中，可能无法保存包含 HipChat 通知的 Watcher。

典型报错与异常栈 #

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

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

或者 room 字段缺失：

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 等字段是否存在。

   # 查看 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 来自模板，确认模板渲染后没有变成空值：

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

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

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

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

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

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

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

排查时需要注意的问题 #

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

4. 如何解决这个错误 #

常用修复思路 #

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

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

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

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

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

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

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

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

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

  // 迁移到 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 适合查看集群的 Watcher 配置、通知渠道状态、错误趋势和消息内容，帮助快速定位 failed to parse hipchat message 是字段问题、结构问题还是渠道问题，并提供可视化的 Watcher 管理和编辑功能。
• INFINI Gateway 可以记录所有 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
• 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
• failed-to-parse-how-to-solve-this-elasticsearch-exception
• watcher-exception-how-to-solve-this-elasticsearch-exception

参考文档 #

• Elasticsearch Watcher HipChat Action 官方文档（6.8）
• Elasticsearch Watcher 官方文档
• Elasticsearch 通知渠道官方文档
• INFINI Console 文档
• INFINI Gateway 文档

附：日志上下文 #

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

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);
}