故障排除

此处提供了一些 DVC 用户可能遇到的问题的解决帮助。

无法从云端拉取数据

用户在运行 dvc pull 和 dvc fetch 时可能会遇到错误，例如 WARNING: 缓存 'xxxx' 未找到。 或 ERROR: 无法从云端拉取数据。最常见的原因是已将更改推送到 Git，但相应的数据未上传到 DVC 远程存储。请确保从原始 项目 执行了 dvc push，然后重试。

打开文件过多错误

部分用户在使用 dvc pull、dvc fetch 和 dvc push 命令时会遇到一个已知问题：[Errno 24] 打开文件过多（在 macOS 上使用 S3 远程存储时尤为常见）。指定的 --jobs 越多，每个下载线程在主机文件系统上需要打开的文件描述符就越多，容易达到系统限制，从而引发此错误。

解决方法通常是提高可打开文件描述符的数量限制：在类 UNIX 系统上可通过 ulimit 实现（例如 ulimit -n 1024），或在 Windows 上增加句柄限制。否则，可以尝试使用更小的 JOBS 值。

无法找到凭据

请确保您已通过标准的 AWS 配置方式设置 AWS 凭据，或者使用 dvc remote modify 设置 access_key_id 和 secret_access_key。

无法连接

请确认您已联网，并能够访问您的 AWS S3 终端节点，或如果已通过 dvc remote modify 显式设置了 endpointurl，请检查该地址是否可达。

存储桶不存在

请确认您的存储桶存在于正确的 region 和/或 endpointurl 中（参见 dvc remote modify）。

无法检测缓存类型

由于缓存目录不存在，导致无法检测支持的链接类型。该目录通常由需要它的 DVC 命令自动创建，但您也可以手动创建（例如 mkdir .dvc/cache），以启用此项检查。

无法获取锁

如果项目中有其他 DVC 进程正在运行，您可能会看到 无法获取锁 的错误提示。如果不是这种情况，通常意味着 DVC 被异常终止，手动删除 .dvc/tmp/lock 中的锁文件即可解决问题。

如果问题仍然存在，可能是您正在 NFS、Lustre 等网络文件系统上运行 DVC。此时，解决方案是启用 core.hardlink_lock，可通过运行以下命令实现：

$ dvc config core.hardlink_lock true

无法在符号链接目录中添加文件

DVC 仅支持将符号链接文件作为 dvc add 的有效目标。如果目标路径是目录的符号链接，或目标路径中包含任何中间目录的符号链接，则 dvc add 将失败。

无可用的缓存类型

当 DVC 在将数据文件从缓存链接到工作区时无法找到有效的文件链接类型，您可能会遇到此错误。要解决此问题，您可能需要重新配置DVC，以使用您的机器上支持的其他链接类型。

重新配置缓存类型后，您可以使用以下命令重新链接工作区中的数据文件：

$ dvc checkout --relink

DVC 无法向 Git 远程端进行身份验证

某些命令需要向 Git 远程端进行身份验证（例如，实验共享）。您可能需要具备写权限（dvc exp push）或读权限（dvc exp list、dvc exp pull）。

建议使用 SSH 进行身份验证。如果您使用 HTTP，可以配置Git 凭据助手（如Git Credential Manager），以便对私有的 HTTP Git 远程端进行身份验证。

像 dvc import 这样的命令会克隆一个不同于当前工作目录的 Git 仓库。为了使这些命令能够从凭据助手中读取信息，必须使用 git config --global 或 git config --system 进行配置。

ssh-add --apple-load-keychain ~/.ssh/ed255

无法打开已序列化的 'index/md5/links' 缓存

当您在同一 DVC 项目目录中使用不同 Python 版本运行 DVC 时，可能会遇到此错误。例如，在 Python 3.8 环境中创建了项目，之后尝试从 Python 3.7 环境更新项目。这是由于创建的临时内部目录可能与较旧的 Python 版本不兼容所致。

在这种罕见情况下，删除相应的临时目录并重试 DVC 命令是安全的。具体来说，删除以下之一：

• .dvc/tmp/index
• .dvc/tmp/md5s
• .dvc/tmp/links

DVC 实验在 Git 浅层克隆中可能失败

在 dvc<=2.45.1 版本中，dvc exp` 命令使用了一些内部 Git 操作，在浅层克隆中可能无法正常工作。请升级到更新版本的 DVC 以解决这些错误。