适用版本： 6.8-8.9
1. 错误异常的基本描述 #
这里的 must not contain whitespace 指的是快照名称 snapshotName 中含有空格，因而被 InvalidSnapshotNameException 拒绝。源码里这条规则紧跟在“不能为空”之后：只要 snapshotName.contains(" ") 为真，请求就不会进入真正的快照创建逻辑。
常见现象 #
- 创建快照请求刚提交就返回失败，通常还没开始扫描任何分片。
- 失败值往往像
daily backup、snapshot 2026-03-31这种带空格的人工命名。 - 使用脚本拼接快照名时，如果拼接符选成空格，也会稳定复现这条异常。
典型报错与异常栈 #
常见日志形态类似下面这样：
InvalidSnapshotNameException[[repo_name:daily backup] Invalid snapshot name [daily backup]; must not contain whitespace]
2. 为什么会发生这个错误 #
快照名称最终会作为仓库中的元数据标识和 API 路径的一部分。空格虽然对人类可读，但对路径解析、转义和脚本兼容都不友好，因此 Elasticsearch 直接把它列为非法字符之一。
常见触发场景包括：
- 手工命名快照时直接输入自然语言短语。
- 自动化脚本用日期和环境名拼接时选择了空格作为分隔符。
- URL 中传入未编码的带空格参数，最终被原样解析到快照名。
- 上游平台没有限制命名字符集，导致非法名称进入 Elasticsearch。
3. 如何排查和解决这个异常和解决这个异常 #
建议按下面的顺序排查：
- 查看实际提交的快照名，确认是否包含空格字符。
- 如果由脚本触发，输出最终组装后的请求路径，不要只看模板。
- 把命名逻辑改为使用
-、_或其他允许字符，而不是空格。 - 修复后重新提交快照请求，确认已通过命名校验。
- 顺手检查同一套命名逻辑是否还可能触发空名、特殊字符或重名问题。
排查时需要注意的问题 #
- URL 编码并不能把“带空格的快照名”变成合法名称，根因仍然是命名规则不允许。
- 不要把它误判为仓库、凭证或 master 节点问题；这条错误发生得更早。
- 如果平台允许用户自由输入名称，最好直接在 UI 层阻止空格输入。
4. 如何解决这个错误 #
常用修复思路 #
- 把快照名中的空格替换成
-或_。 - 在快照创建前增加正则校验，例如只允许字母、数字、短横线和下划线。
- 统一封装命名函数，避免不同脚本各自实现不同规则。
- 给用户或任务调度系统返回更明确的提示，说明不能使用空格。
后续注意事项与推荐建议 #
- 对命名模板做单元测试，确保输出值不含空格和其他非法字符。
- 对人工输入场景给出推荐格式，例如
daily-backup-2026.03.31。 - 建议将“快照命名规范”写入运维手册，减少重复踩坑。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合查看集群健康度、节点指标、索引状态、错误趋势和请求画像，帮助快速判断异常是局部问题还是系统性问题。
- INFINI Gateway 适合部署在 Elasticsearch 前面做请求观测、限流、熔断、缓存和流量治理，尤其适合定位高频错误请求、异常重试和不合理 DSL。
- 如果需要长期治理，建议把异常日志、慢查询、调用来源和变更记录统一接入监控面板，缩短从“发现问题”到“定位根因”的时间。
5. 小结 #
这条异常说明你的快照名在字符级校验阶段就不合规。最有效的做法是统一命名规范，并把空格校验前移到调度平台或脚本层。
相关错误 #
- 不能为空 - 如何解决此 Elasticsearch 异常
- 不能包含 - 如何解决此 Elasticsearch 异常
- snapshot-with-the-same-name-already-exists-如何解决此Elasticsearch异常
附：日志上下文 #
下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：
private static void validate(final String repositoryName; final String snapshotName) {
if (Strings.hasLength(snapshotName) == false) {
throw new InvalidSnapshotNameException(repositoryName; snapshotName; "cannot be empty");
}
if (snapshotName.contains(" ")) {
throw new InvalidSnapshotNameException(repositoryName; snapshotName; "must not contain whitespace");
}
if (snapshotName.contains(";")) {
throw new InvalidSnapshotNameException(repositoryName; snapshotName; "must not contain ';'");
}
if (snapshotName.contains("#")) {
