问题排查

日志关键词: xFormers can't load C++/CUDA extensions

启动或采样时提示 xFormers 的 C++/CUDA 扩展无法加载，或者找不到支持当前输入的 attention 算子。pip 列出包已安装，只能说明 Python 分发包存在，不能证明其中的 GPU 内核可以运行。

日志关键词: no kernel image is available for execution on the device

适用于 PyTorch 或注意力扩展实际调用 GPU 算子时报告 no kernel image。新显卡太新、旧显卡被构建移除、第三方扩展未包含目标架构都可能触发，不能统一称为“显存不够”。

日志关键词: No matching distribution found

适用于 pip 找不到某个依赖版本。先确认完整包名和版本限制，再检查 Python、操作系统、CPU 架构及下载源；这条提示不一定表示项目根本不存在。

日志关键词: expected input

错误指出输入通道数、latent 维度或张量某一轴不符合预期。这里首先检查模型与 VAE、latent 构造节点的配套关系，而不是把所有图像或视频 latent 都当作相同结构。

日志关键词: mat1 and mat2 shapes cannot be multiplied

采样、文本编码或加载适配器时出现矩阵形状不兼容。数字反映当前参与计算的维度，是定位线索，但不能只凭一组数字推出唯一缺失模型。

日志关键词: Expected all tensors to be on the same device

一个运算收到来自不同设备的张量，例如图像在 CUDA、mask 还在 CPU，或者两个分支分别位于不同 GPU。错误指出的是运算边界，不等于整套程序没有识别显卡。

日志关键词: size mismatch

把文件读取、条件编码、采样和 VAE 解码分阶段处理，不靠错误里有 Qwen 就统一重装。

日志关键词: TextEncodeQwenImage21

按技术类名和图结构排查，不把官方模板里的 UUID 直接当成第三方插件名称。

日志关键词: No module named 'pytorch_lightning'

两种导入命名会出现在不同项目和版本中。不要认为安装其中任意一个就一定满足所有节点，也不要把 checkpoint 反序列化失败当成单纯缺包。

日志关键词: No module named 'rotary_embedding_torch'

缺少 Python 位置编码实现不代表缺少一个可下载的模型权重。导入问题解决后，仍需检查节点和模型使用的张量维度与调用接口。

日志关键词: No module named 'deepdiff'

配置比较节点可能在导入 DeepDiff、比较复杂对象或输出比较结果时失败。比较结果显示“不相同”通常是业务结果，不应被当成依赖错误来修复。

日志关键词: No module named 'decord'

视频节点报 decord 缺失、打不开文件或无法启用 GPU 时，要分别检查 Python 绑定、输入媒体和原生构建能力。Torch 能用 CUDA，并不证明 decord 也具备 GPU 解码。

日志关键词: No module named 'webcolors'

配色节点报 AttributeError 时，先看缺的是整个模块，还是旧代码访问的颜色映射。两种错误不能使用同一条“重新安装”建议。

日志关键词: No module named 'blend_modes'

混合节点的异常可能发生在导入，也可能发生在图像数组运算。包名、输入通道、数组类型和透明度参数需要分别核对，不能用“强制转成四通道”覆盖所有情况。

日志关键词: No module named 'soundfile'

音频节点不能读取文件时，先看导入是否成功，再看底层库能否加载，最后检查输入文件。安装 FFmpeg 不等于已经补上 SoundFile 的所有依赖。

日志关键词: No module named 'OpenGL_accelerate'

某些三维或渲染节点可能分别依赖 PyOpenGL、可选的加速绑定和可用图形上下文。先确认异常发生在 Python 导入，还是运行时建立渲染上下文。

日志关键词: No module named 'argostranslate'

翻译节点可能在导入 Python 包时失败，也可能已能导入但没有所需语言模型。先确认节点实际调用的是 Argos Translate，不要因为名称相似安装别的翻译库。

日志关键词: No module named 'nvvfx'

日志里的 nvvfx 可能来自节点封装或原生 SDK 接口。只凭这一行，不能认定存在同名、可信且适用于当前环境的 pip 安装包。

日志关键词: No module named 'timm'

同一个节点可能先导入 timm，再按名称创建模型，最后获取预训练权重。先确认失败阶段，避免把所有错误都当成 Python 缺包。

日志关键词: CRC Failed

下载完成但解压报 CRC、Data Error 或无法识别压缩包时，不要继续启动残缺的 Python。先验证压缩包，再排查解压工具、分卷、磁盘和路径。

日志关键词: No module named simpleeval

先查表达式节点实际依赖，再检查允许的名称、运算和输入，不用 Python eval 代替安全边界。

日志关键词: workflow templates

更新之后，新教程里的模板或界面仍然不存在。ComfyUI 核心源码、桌面应用、前端包、自定义节点与模板并不是一个不可分割的版本号。

日志关键词: Bad git executable

适用于 Manager 安装/更新仓库时找不到 Git，或系统终端可以执行 Git、ComfyUI 进程却不可以。这里要核对的是服务进程的环境，不只是当前打开的另一个终端。

日志关键词: Float8_e4m3fn

在 Mac 上加载某个 FP8 模型或执行节点时，出现转换到 MPS 不支持的 dtype 提示。需要确定是权重加载、解量化还是运算阶段受限，而不能据文件名认定所有量化模型都不支持。