---
title: "启动 users 文件监听失败 - 如何解决此 Elasticsearch 异常"
date: 2026-04-03
lastmod: 2026-04-03
description: "failed to start watching users file 表示 Elasticsearch 在为 file realm 的 users 文件注册资源监听器时失败，通常与父目录不可访问或文件系统监听能力有关。"
tags: ["file realm", "users", "watcher", "安全"]
summary: "适用版本： 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."
---


> **适用版本：** 6.8-8.x

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

`failed to start watching users file [<absolute-path>]` 表示 Elasticsearch 不是在读取 `users` 文件内容时失败，而是在向 `ResourceWatcherService` 注册该文件的监听器时失败。这个异常通常出现在节点启动或安全配置初始化阶段。

### 常见现象

- 节点可能仍能启动，但 file realm 文件热更新失效，或启动流程直接报错。
- 同一时间窗口内可能没有 `users` 文件内容解析错误，因为问题发生在监听器注册之前。
- 日志根因通常是 `IOException`，与目录、文件系统事件或权限有关。

### 典型日志

```text
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. 排查步骤

1. 检查报错中的文件及其父目录是否真实存在。
2. 验证 Elasticsearch 运行用户对父目录具有读取和遍历权限。
3. 在容器环境中确认卷挂载不是只读异常或短生命周期目录。
4. 检查宿主机文件监听资源限制和相关内核参数。
5. 若只在特定节点复现，重点排查该节点的存储层和挂载方式。

## 5. 处理建议

### 修复方法

- 修正 `users` 文件路径及其父目录权限。
- 将安全配置文件放在本地稳定文件系统上，避免使用不可靠挂载。
- 恢复或提高系统层面的 watcher 资源限制。
- 必要时重建配置目录，排除损坏的卷或异常符号链接。

### 预防建议

- 对 file realm 相关目录做启动前健康检查。
- 统一节点的挂载方式和安全配置目录结构。
- 将文件监听异常纳入启动日志告警。

## 相关错误

- [could-not-read-users-file-path-toabsolutepath：无法读取 users 文件](/knowledge-base/elasticsearch_error/could-not-read-users-file-path-toabsolutepath-how-to-solve-this-elasticsearch-exception/)
- [failed-to-start-watching-the-user-roles-file-file-toabsolutepath：启动 users_roles 文件监听失败](/knowledge-base/elasticsearch_error/failed-to-start-watching-the-user-roles-file-file-toabsolutepath-how-to-solve-this-elasticsearch-exception/)
- [failed-to-watch-file-from-setting：监听配置文件失败](/knowledge-base/elasticsearch_error/failed-to-watch-file-from-setting-how-to-solve-this-elasticsearch-exception/)

## 附：日志上下文

```java
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);
```