Elasticsearch 报 "No handler for type [keyword] declared on field" 错误怎么办？

当错误具体指出不识别 keyword 时，通常是 Elasticsearch 版本太老（2.x 或更早），不认识 keyword 类型——keyword 是 ES 5.0 才引入的。解法二选一：升级 ES，或把 mapping 改回旧版语法。

原因对照

修法一：升级集群（推荐）

ES 2.x 早已停止维护，安全与性能都有问题。应先备份并按支持的升级或迁移路径处理索引、插件和客户端兼容性，不能直接跨所有大版本升级；支持的版本中 mapping 使用 keyword。

修法二：改写 mapping 兼容旧版

{
  "mappings": {
    "doc": {
      "properties": {
        "hostname": { "type": "string", "index": "not_analyzed" }
      }
    }
  }
}

注意连锁反应

• 改 mapping 只对新索引生效，存量索引要 reindex；
• 客户端代码/模板（如 Logstash、Filebeat 自带的索引模板）也要与集群版本匹配——Filebeat 新版配 ES 老版常触发这个错，选择受支持的版本组合并提供兼容模板；仅关闭模板自动加载并不能修复客户端协议或字段类型不兼容。

常见问题（FAQ）

Q：怎么确认集群版本？ curl localhost:9200 返回 JSON 里的 version.number。

Q：text 和 keyword 能同时用吗？ 5.x+ 可以：主类型 text 用于全文，子字段 .keyword 用于精确匹配与聚合。