文档中心

对象存储

tosfsspec

tosfsspec 故障处理

tosfsspec 故障处理

本文主要介绍一些在使用 tosfsspec 时可能遇到的常见问题及定位方法。

问题定位

当您遇到问题时，可以开启 fsspec 和 tosfsspec 的调试日志来帮助定位问题。以下为一段可直接在代码中独立使用的示例：

import logging​
logging.basicConfig(level=logging.DEBUG)​
logging.getLogger('fsspec').setLevel(logging.DEBUG)​
logging.getLogger('tosfsspec').setLevel(logging.DEBUG)​

这段代码会打印出详细的底层操作和网络请求信息，帮助您分析问题。

常见问题

ValueError: The part_size must be >= 4194304

问题现象：

初始化 TosFileSystem 或调用 fs.open() 时出现 ValueError，提示part_size或block_size必须大于等于 4MB。

问题原因：

TOS 对分片上传设置了最小分片大小限制。写入模式（'wb'、'ab'）下，block_size参数决定单个分片大小；若小于 4MB，将触发该错误。

解决方案：

写入模式使用 fs.open(..., mode='wb') 或 fs.open(..., mode='ab') 时，确保block_size 参数的值大于或等于 4 * 1024 * 1024。

初始化 TosFileSystem(part_size=...) 时，确保part_size参数的值大于或等于 4 * 1024 * 1024。

若不确定合适值，可不显式设置 block_size，由 tosfsspec 使用默认值 8MB。

权限错误（例如TosException: status=403）

问题现象：

执行 ls, open, put 等操作时收到 tos.exceptions.TosException，状态码为 403 (Forbidden)。

问题原因：

AK/SK 错误：提供的 key (Access Key ID) 或 secret (Secret Access Key) 不正确或已失效。

IAM 策略限制：您使用的账号所附加的 IAM 策略没有执行相应操作的权限。例如仅有读取权限（tos:GetObject）但缺少写入权限（tos:PutObject）或列举权限（tos:ListObjects）。

IP 白名单限制： Bucket 或账号设置了 IP 白名单，而您的访问来源 IP 不在允许范围内。

解决方案：

核对 AK/SK：确认无前后空格、处于启用状态、与使用账号匹配。

检查 IAM 策略：确认包含所需权限，常见权限包括读取 tos:GetObject、写入 tos:PutObject、列举 tos:ListObjects。

确认网络出口 IP：检查是否被 Bucket 的访问控制策略允许。

目录操作与预期不符

问题现象：

路径下面有文件，但您用 fs.isdir('tos://my-bucket/some/path/') 去判断时，返回 False。

目录里已经无内容，想用 fs.rmdir() 把目录删掉，但无法删除。

问题原因：

TOS 的 FNS（扁平命名空间）Bucket 实际上没有真正的目录概念。目录是通过以 / 结尾的 0 字节对象来模拟的。

isdir 检查的是是否存在一个名为 some/path/ 的对象。如果这个对象不存在（即使 some/path/file.txt 存在），isdir 也会返回 False。

rmdir 只能删除代表目录的 0 字节对象，且要求该对象下没有任何其他对象（即 prefix 为该目录的对象不存在）。

解决方案：

使用 fs.makedirs(path, exist_ok=True)显式创建目录，确保目录对象被创建。

判断一个路径是否为目录，更可靠的方式是检查其名称是否以 / 结尾，或者通过 fs.info(path)['type'] == 'directory'。

删除非空目录，请使用 fs.rm(path, recursive=True)。

ValueError: The maxdepth is not supported for hns bucket

问题现象：

在 walk(), glob(), rm(recursive=True) 等递归操作中，对某个 Bucket 传入maxdepth 参数时，出现ValueError。

问题原因：

maxdepth 参数用于限制递归遍历的深度，仅在 FNS （扁平命名空间）类型的 Bucket 中受支持。HNS （层级命名空间）类型的 Bucket 使用原生的目录结构，其底层遍历 API 不支持深度限制。

解决方案：

请确认您的 Bucket 类型。

若为 HNS Bucket，移除maxdepth 参数。并自行在业务代码中处理深度限制，例如在 walk 的循环中加入计数器。

如果必须使用 maxdepth，请考虑将数据迁移到 FNS 类型的 Bucket 中。

FileNotFoundError

问题现象：

访问一个您认为应该存在的路径时，返回 FileNotFoundError。

问题原因：

路径确实不存在：Bucket 名称或 Object Key 拼写错误。

权限不足：您缺少该对象的 tos:GetObject 或 tos:ListObjects 权限时，在某些情况下也可能表现为未找到。

目录标记缺失：对 fs.info() 而言，当路径是目录但不存在对应的目录标记对象（以 / 结尾的 0 字节对象）时，也可能返回 FileNotFoundError。

解决方案：

使用 fs.ls() 逐级列举父路径，确认路径各层级（Bucket、前缀、对象名）均正确。

检查并补齐 IAM 权限。

针对目录场景，优先用 fs.ls(path) 检查内容，而不是仅依赖 fs.info(path)。

最近更新时间：2026.03.19 17:45:47

这个页面对您有帮助吗？

有用

有用

无用

无用