知仓学习社知仓学习社
huggingface_hub 本地找不到文件：LocalEntryNotFoundError / EntryNotFoundError / 全站资源搜索
搜索 更新 2026-10-02
报错 070 网络、下载与访问（含国内网络环境） 含未核实说明

huggingface_hub 本地找不到文件：LocalEntryNotFoundError / EntryNotFoundError

报错原文（原样） 
huggingface_hub.utils._errors.LocalEntryNotFoundError: An error happened while trying to locate the file on the Hub and we cannot find the requested files in the local cache. Please check your connection and try again or make sure your Internet connection is on.
（注：以上为转述文本，非逐字原文。）
检索关键词 LocalEntryNotFoundError、huggingface_hub.utils._errors、cannot find the requested files in the local cache、EntryNotFoundError、snapshot_download、hf_hub_download
先看这一句 自定义节点在下载/加载模型时报 LocalEntryNotFoundError 或 EntryNotFoundError，节点标红、工作流中断；重复运行依旧失败。
适用版本 全版本通用，取决于节点所依赖的 huggingface_hub 版本与调用方式 · 核实日期 2026-09-26 · 状态 可能已过期，正在复核
适用环境：Windows 便携版、秋叶/绘世整合包、ComfyUI Desktop、Linux + 云 GPU、Docker/服务器

现象与触发场景

常见触发场景：

  • 节点在运行时调用 hf_hub_download / snapshot_download，联网失败退回本地缓存也未命中
  • 之前下载中断或缓存被清理
  • 仓库名/文件名写错或该 revision 下不存在这个文件（对应 EntryNotFoundError）
  • 设置了 local_files_only 或离线模式，但本地并没有缓存

根因

  • huggingface_hub 的下载流程是「先联网 → 联网失败则查本地缓存」，两者都失败时分别抛 LocalEntryNotFoundError（网络+缓存都不可用）或 EntryNotFoundError（联网成功但该文件在仓库中不存在）。
  • 国内直连 huggingface.co 失败是最常见诱因，节点作者通常不会额外处理这个异常，于是直接把堆栈抛到界面上。
  • ComfyUI 里也存在同一类报错被包成 '(MaxRetryError(...), ... Returning existing local_dir ... as remote repo cannot be accessed in snapshot_download' 的形式，说明代码已尝试回落但本地目录不存在。

解决步骤

已按「最可能有效」排序。请从上往下做，每做完一步用「验证」确认，不要一次改五处。

  1. 先区分是网络问题还是文件名问题
    LocalEntryNotFoundError 明确指向网络+缓存双重失败；EntryNotFoundError 说明连接是通的、但仓库里没有这个文件（多半是仓库名、分支或文件名写错）。看报错类型再选方向，不要一律当成网络问题。
  2. 设置 HF_ENDPOINT 镜像后重试下载
    让 huggingface_hub 走国内镜像完成下载，缓存落地后后续启动就会直接命中本地缓存，不再依赖网络。
    setx HF_ENDPOINT https://hf-mirror.com
    # Linux
    export HF_ENDPOINT=https://hf-mirror.com
  3. 手动下载后放到节点要求的本地目录
    在 ModelScope / hf-mirror 网页端下载对应文件，放到节点 README 或报错日志里指明的目录（常见为节点目录下的 models/ 子目录，或 ComfyUI/models/ 下对应子目录）。放好后重启 ComfyUI。

验证是否修好

重启后再次触发该节点：不再出现 LocalEntryNotFoundError；重复执行第二次时日志应显示直接命中本地缓存。

补充说明

[未核实] 本条 error_text 为 huggingface_hub 该异常的通行英文措辞，未能在本轮检索中取到 ComfyUI 场景下逐字相同的堆栈，故 error_text_verbatim 标为 false。真实来源中可见的相近原文是 ComfyUI issue #7185 中的："Returning existing local_dir `/data/ComfyUI/custom_nodes/comfyui-mimicmotionwrapper/models/DWPose` as remote repo cannot be accessed in `snapshot_download` ((MaxRetryError("HTTPSConnectionPool(host='huggi..."。

来源

按可信度排列：官方 issue / 官方文档 > 节点仓库 issue > 社区帖 > 中文社区文章。 链接以纯文本给出（本站不做站外跳转），需要核对时请自行复制到浏览器打开。
  1. [167] （官方 issue）　PytorchStreamReader failed reading zip archive: failed finding central　https://github.com/Comfy-Org/ComfyUI/issues/7185
  2. [168] （中文社区）　ComfyUI报错：huggingface_hub.local_entry_not_found - CSDN 问答　https://ask.csdn.net/questions/8830209
  3. [169] （官方文档）　HfApi Client — RepositoryNotFoundError / RevisionNotFoundError / Entry　https://huggingface.co/docs/huggingface_hub/v0.35.0.rc1/package_reference/hf_api
本条的可靠性边界 下面这些位置带 [未核实] 标记，是采集时没找到一手来源的部分，请自行验证：
  • 补充说明

这条报错要用到的东西

按本条报错所属的类别（网络、下载与访问（含国内网络环境））列出站内相关的下载包与板块入口。 它们不是「必须下载才能修好」，而是这一类问题里最常要动到的东西；具体怎么做，以上面的解决步骤为准。

ComfyUI 权重库（167 个文件 / 约 1187 GB）按 ComfyUI 的 models 目录分好类的 167 个权重文件 / 每个文件一份说明（放哪、被哪些工作流引用） 待挂载
模型档案按仓库看体积，估一下要下多久 板块

同一类别的其他条目

【067】启动或加载工作流时连不上 huggingface.co，控制台报最大重试次数已超过 有来源 【068】SSL 证书校验失败：CERTIFICATE_VERIFY_FAILED unable to get local issuer certificate 有来源 【069】transformers 报 We couldn't connect to 'https://huggingface.co' to load this file 有来源 【071】Gated 仓库无权访问：需要登录并同意协议（Llama / Flux 等） 含未核实 【072】ComfyUI-Manager 安装节点失败：连不上 GitHub（Failed to connect to github.com port 443） 有来源
这个解法对你有效吗 记录只存在你自己的浏览器里，不需要注册账号。

返回报错库