问题排查

日志关键词: torchscale

安装一个视觉或多模态节点后，另一个节点可能要求不同 timm 版本。先把要求来自哪个包画清楚，再判断共用环境是否可行。

日志关键词: mediapipe

节点可能在 pip 解析依赖时被阻止，也可能装好后在导入原生扩展时失败。先读取当前 MediaPipe 发行包的依赖，不把历史版本的限制套到所有新版本。

日志关键词: Descriptors cannot be created directly

该错误可能由旧版生成的 Python 消息代码与运行库不匹配引起。不要只看到 protobuf 就删除或降级整个环境中的所有相关依赖。

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

人脸相关节点提示 dlib 缺失时，先区分根本没有 Python 绑定，还是安装过程中原生编译失败。不要下载不明来源的 DLL 或 wheel 拼进环境。

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

看到缺少 flash_attn 或 wheel 构建失败，不要立即替换 Torch。节点使用的 FlashAttention 路线、GPU、操作系统和编译工具需要同时匹配。

日志关键词: No module named segment_anything

检查节点采用的具体实现，不把 SAM、SAM2 和不同 GroundingDINO 封装当成同一个包。

日志关键词: No module named mmcv

区别 mmcv 与 mmcv-lite，并将源码构建失败和运行期扩展加载失败分开处理。

日志关键词: No module named cv2

区分普通版、contrib 和 headless，检查同一命名空间的重复安装，再处理 DLL 或原生库错误。

日志关键词: No module named onnxruntime

区分 onnx、onnxruntime、GPU 构建与会话实际使用的执行提供程序，避免把所有错误当成缺包。

日志关键词: qwen-tts

安装语音节点后出现 Transformers 冲突时，应先识别节点包装层和 Qwen TTS 包的各自要求。一个项目的精确依赖锁定，不能当成所有模型共用的推荐版本。

日志关键词: No module named sqlalchemy

将数据库库缺失、数据库连接和迁移状态分开检查，不默认删除数据库或重建全部表。

日志关键词: Windows protected your PC

Windows 提示不认识应用、阻止启动或隔离文件时，先识别是哪种防护在起作用。文件名看起来熟悉，不能证明下载物没有被替换。

日志关键词: Bad linked input

通过 API 构造 inputs 时，列表值被当作节点连接，但不符合连接结构。特别是业务参数本身为数组时，不能假设任何 JSON 列表都会被当作普通值原样传入。

日志关键词: Return type mismatch between linked nodes

上游输出的接口类型与下游输入声明不同，服务端拒绝执行。例如 IMAGE、LATENT、MODEL 和 CONDITIONING 在工作流里承担不同角色，不能仅因界面允许拖动就视为可互换。

日志关键词: No module named kornia

先判断主包缺失还是某项功能缺少额外依赖，不把最新安装命令强加给旧节点。

日志关键词: No module named spandrel

把库的安装、模型架构识别和权重来源分别核对，不因后缀相同就判断能够加载。

日志关键词: No module named transformers

先确定失败发生在导入、模型初始化还是联网获取文件，保留 revision 和缓存上下文。

日志关键词: No module named safetensors

用失败阶段区分 Python 依赖和模型文件问题，保留来源、版本、大小与校验记录。

日志关键词: No module named llama_cpp

先确认 llama-cpp-python 的实际环境与后端，再处理编译日志或模型加载，不按 GGUF 后缀乱换加载器。

日志关键词: No module named nunchaku

检查 wheel 的 Python、系统与 Torch 标签，避免把节点安装成功和底层推理库安装成功混为一谈。

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

使用 FaceID 时出现 insightface 模块缺失、构建 wheel 失败，或者包安装后仍无法初始化。这里需要分别确认解释器、二进制构建、运行后端与模型资源。

日志关键词: IPAdapter model not found.

已下载 IPAdapter 权重，但统一加载器仍无法自动选择文件。首先检查所用加载器的规则；“文件在磁盘上”与“能够按预设自动找到”并不是一回事。

日志关键词: ClipVision model not found.

参考图工作流缺少视觉编码器，或加载后在图像嵌入阶段出现维度不匹配。先确认需要的是 CLIP Vision，而不是 CLIPTextEncode 对应的文本编码器。

日志关键词: No workflow found

拖入一张示例图、截图或转存后的图片，没有出现预期节点图。这并不自动意味着 ComfyUI 导入功能坏了；需要先确定原始文件是否包含可恢复的工作流信息。