解决 Elasticsearch TimeoutException 报错，优先检查查询语句复杂度，其次在客户端配置或查询参数中增加 timeout 值。直接增加等待时间可能掩盖性能瓶颈，适用场景为临时止血或确认资源充足后的长任务，风险边界是可能占用更多线程资源导致集群压力增大。

命令速用版

在查询 URL 后追加参数即可临时增加等待时间，客户端代码需修改配置对象。

GET /_search?timeout=30s
{
  "query": { ... }
}

Java High Level REST Client 配置需设置 RequestOptions 超时：

RequestOptions.Builder options = RequestOptions.DEFAULT.toBuilder();
// 具体超时设置依赖客户端版本及 HTTP 底层实现

Python 客户端示例：

es = Elasticsearch([...], request_timeout=30)

为什么会这样

TimeoutException 通常由网络传输耗时或服务端查询执行耗时超过阈值触发。

客户端默认等待时间有限，复杂聚合或大数据量扫描会导致服务端处理时间延长。若网络波动或集群负载高，响应延迟会增加，触发客户端主动断开或服务端保护机制。

分步处理

第一步：定位超时来源。

查看客户端日志区分是 SocketTimeoutException 还是 Elasticsearch 返回的 504 Gateway Timeout。客户端超时常表现为连接重置，服务端超时通常有明确错误信息。

第二步：调整客户端超时配置。

在 HTTP 客户端中增加 socket_timeout 值。Python 客户端示例：elasticsearch.Elasticsearch(..., request_timeout=30)。

第三步：调整查询参数 timeout。

在 search API 请求体或 URL 参数中添加 timeout 字段，告知服务端允许的最大执行时间。

第四步：评估服务端配置。

检查 elasticsearch.yml 中的 search.default_search_timeout，默认通常无限制或依赖客户端，修改需重启节点。

怎么验证是否生效

执行相同查询语句，观察响应状态码是否为 200 且无异常抛出。

检查客户端日志不再出现 TimeoutException，服务端慢查询日志（slow log）记录的执行时间在设定阈值内。

常见坑

避免将超时时间设置为无限长，这会导致线程池阻塞。

增加超时时间不能解决内存不足问题，若堆内存溢出，增加等待时间只会延迟报错。

注意网关层超时，Nginx 或负载均衡器的超时设置可能低于客户端设置。

常见问题

默认超时时间是多少？

取决于客户端库实现，无统一标准，常见 HTTP 客户端默认值通常在 30 秒左右。

增加超时会影响性能吗？

单纯增加超时不影响执行速度，但长任务会占用线程资源，可能降低并发处理能力。

为什么改了配置还报错？

可能中间代理层或负载均衡器限制了连接时长，需检查链路中所有节点的超时配置。