问题排查

日志关键词: Required input is missing

服务端在执行前发现节点缺少必需输入。错误通常会给出节点和输入名；先修复这个明确缺口，再判断是否还有上游问题。

日志关键词: has no class_type

提交的工作流中某个节点缺少 API 执行所需的 class_type。相同 missing_node_type 错误分类还可能用于类名存在但服务端不认识，因此必须同时查看 message 和 extra_info。

日志关键词: prompt_outputs_failed_validation

原生 ComfyUI API 拒绝提交工作流。HTTP 400 只说明这次请求不符合要求，具体原因应从 error 与 node_errors 中提取，不能一律当成网络不稳定重试。

日志关键词: execution_cached

点击运行后任务很快结束，没有在预想目录看到新图片或视频。这可能是缓存命中、没有新的保存操作、输出写到临时目录，或者客户端把某个事件误当作成功。

日志关键词: Failed to fetch dynamically imported module

浏览器打不开正常画布、控件消失或白屏，但后端终端可能仍在运行。需要区别静态资源加载失败、前端扩展冲突和后端根本没启动，不能看到白屏就重装所有模型。

日志关键词: Connection refused

浏览器或脚本无法连接 ComfyUI。localhost 指的是发起访问的那台设备；本机、容器、Notebook、远程服务器和手机之间的地址含义不同，不能只复制一段固定 URL。

日志关键词: Value not in list

运行时 ckpt_name、lora_name 或其他下拉参数不在当前选项中。通常需要检查扫描目录、文件名、正在运行的实例和下拉框旧值，但这个错误也可发生在采样器等非文件选项上。

日志关键词: VAEDecode

采样进度已经结束，但 VAE Decode 或视频解码节点失败，导致没有最终图片或视频。这与采样开始就显存不足不同：已经生成的 latent 仍需要进一步转换为像素。

日志关键词: CUDA out of memory

任务在 GPU 上分配内存失败。先定位失败发生在模型加载、采样、VAE 解码还是其他节点，再决定降低哪个负载。显卡标称容量、模型文件体积和本次实际可用显存不是同一个数字。

日志关键词: torch.cuda.is_available() = False

适用于明确准备使用 NVIDIA GPU，但当前 Python 检测不到可用 CUDA 设备。False 只是当前进程无法使用 CUDA 的结果，应从构建、设备可见性与驱动逐层排查。

日志关键词: Torch not compiled with CUDA enabled

适用于节点或启动过程请求 CUDA，却发现当前 PyTorch 没有对应构建能力。NVIDIA 环境与 Mac/CPU 上误用 CUDA 专属节点必须分开判断，修复方向完全不同。

日志关键词: _ARRAY_API not found

适用于安装或更新节点后，导入 NumPy 相关扩展时出现 ABI 报错。问题通常发生在编译扩展与 NumPy 的二进制接口之间，而不是工作流连线本身。

日志关键词: ImportError: cannot import name

适用于升级后某个节点导入失败，或提示某模块缺少过去使用的名称、属性。它与 No module named 不同：模块可能已经存在，只是调用的接口或导入关系不再满足要求。

日志关键词: ModuleNotFoundError

适用于启动或执行自定义节点时提示缺少 Python 模块。命令行显示“已安装”仍可能是另一个 Python 的结果；Windows Portable 尤其需要区分系统 Python 与内置解释器。

日志关键词: Missing Node Types

适用于导入他人工作流后出现红色缺失节点、运行时找不到节点类型的情况。先保存工作流副本和原始下载地址；不要把“缺失节点”自动理解成电脑里完全没有相关文件。

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

Hydra 的导入名和常见分发包名不同。模块缺失与配置搜索路径错误要分别处理，不要把工作流导入失败归结为随便安装一个同名包。

日志关键词: File name too long

解压、Git 检出或安装节点时出现文件名过长，先找出失败的完整路径及执行程序。不要直接移动正在使用的虚拟环境，也不要只改注册表就认定所有程序都会支持长路径。

日志关键词: Dependency cycle detected

工作流某个输出依赖它自己，或者多个节点形成闭环，校验器无法找到正常的数据先后顺序。它不同于有专用循环语义的节点或受支持的控制流，不能仅按画布线条看起来绕了一圈判断。

日志关键词: Custom validation failed for node

自定义验证器主动拒绝与抛出异常是两类错误；先读取对应 node_errors，再决定检查输入、资源还是节点代码。

日志关键词: invalid_input_type

转换失败与超出当前节点范围要分开检查；先核对请求实际提交的值，不要直接改节点定义或统一截断数字。

日志关键词: No module named scipy

保留实际模块名与运算错误，避免把数值、形状和求解器异常都当作安装问题。

日志关键词: Input contains (near) NaN/+-Inf

视频合成时 AAC 或其他音频编码过程失败，stderr 指出输入含非有限值。需要从进入编码器的音频向前检查，而不是仅凭 FFmpeg 报错就认为编码器未安装。

日志关键词: No module named av

分别检查 PyAV 的 Python 入口、其使用的多媒体库，以及节点调用的外部 FFmpeg 程序。

日志关键词: sensevoice-onnx

旧故障线索提到 setuptools 上限，但不能据此直接给你的整个环境降级。先核对安装来源、包版本以及错误究竟来自构建过程还是运行依赖。