适用版本： 6.8-8.x
1. 错误异常的基本描述 #
failed to start watching users file [<absolute-path>] 表示 Elasticsearch 不是在读取 users 文件内容时失败，而是在向 ResourceWatcherService 注册该文件的监听器时失败。这个异常通常出现在节点启动或安全配置初始化阶段。
常见现象 #
- 节点可能仍能启动，但 file realm 文件热更新失效，或启动流程直接报错。
- 同一时间窗口内可能没有
users文件内容解析错误，因为问题发生在监听器注册之前。 - 日志根因通常是
IOException，与目录、文件系统事件或权限有关。
典型日志 #
ElasticsearchException: failed to start watching users file [/usr/share/elasticsearch/config/users]
Caused by: java.io.IOException
2. 源码表明了什么 #
源码会先基于 file.getParent() 创建 FileWatcher，再把它注册到 watcherService。因此只要父目录不可访问、监听服务无法注册、底层文件系统不支持或系统资源受限，就会抛出当前异常。
3. 常见原因 #
users文件所在目录不存在，或路径解析错误。- Elasticsearch 用户对父目录缺少访问权限。
- 底层文件系统、容器卷或网络存储不支持稳定的文件监听。
- 节点的文件句柄、watcher 资源或系统限制已耗尽。
4. 排查步骤 #
- 检查报错中的文件及其父目录是否真实存在。
- 验证 Elasticsearch 运行用户对父目录具有读取和遍历权限。
- 在容器环境中确认卷挂载不是只读异常或短生命周期目录。
- 检查宿主机文件监听资源限制和相关内核参数。
- 若只在特定节点复现，重点排查该节点的存储层和挂载方式。
5. 处理建议 #
修复方法 #
- 修正
users文件路径及其父目录权限。 - 将安全配置文件放在本地稳定文件系统上，避免使用不可靠挂载。
- 恢复或提高系统层面的 watcher 资源限制。
- 必要时重建配置目录，排除损坏的卷或异常符号链接。
预防建议 #
- 对 file realm 相关目录做启动前健康检查。
- 统一节点的挂载方式和安全配置目录结构。
- 将文件监听异常纳入启动日志告警。
相关错误 #
- could-not-read-users-file-path-toabsolutepath：无法读取 users 文件
- failed-to-start-watching-the-user-roles-file-file-toabsolutepath：启动 users_roles 文件监听失败
- failed-to-watch-file-from-setting：监听配置文件失败
附：日志上下文 #
FileWatcher watcher = new FileWatcher(file.getParent());
watcher.addListener(new FileReloadListener(file; this::tryReload));
try {
watcherService.add(watcher; ResourceWatcherService.Frequency.HIGH);
} catch (IOException e) {
throw new ElasticsearchException("failed to start watching users file [{}]"; e; file.toAbsolutePath());
}
}
public void addListener(Runnable listener) {
listeners.add(listener);
