适用版本： 6.8-8.11
1. 错误异常的基本描述 #
在快照恢复或底层文件元数据解析过程中，如果 physicalName 缺失或不合法，会报：
missing or invalid physical file name [physicalName]
2. 为什么会发生这个错误 #
这类异常来自 FileInfo / StoreFileMetadata 解析，不是普通搜索请求问题。源码会先校验 name、physicalName、length、writtenBy、checksum 等字段；如果 physicalName == null 或不是合法文件名，就直接抛出解析异常。
也就是说，元数据记录本身不完整或被破坏了。
3. 如何排查和解决这个异常 #
- 确认异常出现在快照恢复、仓库元数据加载还是文件列表解析阶段。
- 检查相关元数据文件是否损坏、缺失或被手工修改。
- 查看最近是否有异常中断的恢复、复制或迁移操作。
4. 如何解决这个错误 #
方案一：恢复完整元数据 #
优先从可信来源重新获取完整快照/元数据文件。
方案二：检查文件名合法性 #
如果有中间程序处理过元数据，确认没有把文件名改成非法形式。
方案三：重新执行恢复流程 #
若元数据已不可信，通常需要重新恢复或重新生成受影响的数据。
5. 预防建议 #
- 不要手工修改底层元数据文件。
- 对快照和恢复流程做完整性校验。
- 升级和迁移时使用官方支持链路，避免产生半成品元数据。
6. 小结 #
missing or invalid physical file name 说明底层文件元数据已不完整。修复重点在于恢复可信元数据来源，而不是在查询层继续排查。
相关错误 #
- missing-or-invalid-written-by-writtenby-how-to-solve-this-elasticsearch-exception
- missing-affix-file-for-hunspell-dictionary-%25s-how-to-solve-this-elasticsearch-exception
- the-required-field-option-fieldname-field-getpreferredname-is-missing-how-to-solve-this-elasticsearch-exception
附：日志上下文 #
// 验证文件信息是否完整
if (name == null || Strings.validFileName(name) == false) {
throw new ElasticsearchParseException("missing or invalid file name [" + name + "]");
} else if (physicalName == null || Strings.validFileName(physicalName) == false) {
throw new ElasticsearchParseException("missing or invalid physical file name [" + physicalName + "]");
} else if (length < 0) {
throw new ElasticsearchParseException("missing or invalid file length");
} else if (writtenBy == null) {
throw new ElasticsearchParseException("missing or invalid written_by [" + writtenBy + "]");
} else if (checksum == null) {
