Krita-AI-Diffusion故障排除手册：常见错误代码解析
项目地址: https://gitcode.com/gh_mirrors/kr/krita-ai-diffusion Krita-AI-Diffusion作为Krita的AI绘图插件，在使用过程中可能会遇到各类错误。本文档汇总了常见错误代码及其解决方案，帮助用户快速定位并解决问题。手册涵盖网络连接、资源缺失、版本兼容性等六大类问题，每个错误均提供错误描述、可能原因及分步解决方法，并标注相关代码模块位置以便深入排查。
网络连接错误
网络连接问题通常表现为服务器无法访问或通信中断，主要涉及ai_diffusion/connection.py和ai_diffusion/network.py模块。
错误E100：连接超时（NetworkError 5）
错误描述：Connection timed out, the server took too long to respond
可能原因：本地服务器未启动、网络访问限制或服务器地址配置错误。
解决步骤：
- 检查服务器状态：通过任务管理器确认ComfyUI进程是否运行
- 验证服务器地址：打开ai_diffusion/settings.py确认
server_url配置正确 - 测试网络连通性：执行命令
curl http://localhost:8188检查服务器响应
图1：服务器连接配置界面
错误E101：权限验证失败（401 Unauthorized）
错误描述：Unauthorized access - invalid or expired token
可能原因：云服务访问令牌过期或未正确配置。
解决步骤：
- 重置访问令牌：在插件设置中点击"Sign Out"后重新登录
- 清除缓存数据：删除
~/.config/krita-ai-diffusion/access_token文件 - 重新授权：通过菜单"Settings > AI Diffusion > Sign In"获取新令牌
相关代码位于ai_diffusion/connection.py#L104的权限验证逻辑。
资源缺失错误
资源缺失错误通常由于模型文件、自定义节点或依赖库未正确安装，主要涉及ai_diffusion/resources.py和ai_diffusion/server.py模块。
错误E200：模型文件缺失（MissingResources）
错误描述：Required model files not found in specified path
可能原因：首次安装未完成资源下载或模型文件被意外删除。
解决步骤：
- 运行资源验证：执行
python scripts/download_models.py重新下载缺失模型 - 检查存储路径：确认ai_diffusion/settings.py中
models_path指向正确目录 - 手动安装：将缺失模型文件复制到
ComfyUI/models/checkpoints目录
图2：模型文件目录结构示例
错误E201：自定义节点缺失
错误描述：Missing required custom nodes: [node_name]
可能原因：ComfyUI自定义节点未正确安装。
解决步骤：
- 检查节点安装状态：确认ai_diffusion/resources.py中
required_custom_nodes列表 - 重新安装节点：删除
ComfyUI/custom_nodes目录后重启插件触发自动安装 - 验证安装日志：查看
~/.local/share/krita-ai-diffusion/server.log确认节点安装成功
版本兼容性错误
版本不兼容问题主要涉及ComfyUI版本、Python依赖库版本匹配，相关代码位于ai_diffusion/comfy_client.py和ai_diffusion/server.py。
错误E300：ComfyUI版本过低
错误描述：Prompt ID mismatch - Please update ComfyUI to 0.3.45 or later!
可能原因：ComfyUI版本低于0.3.45，与插件不兼容。
解决步骤：
- 检查当前版本：查看
ComfyUI/__init__.py中的__version__字段 - 执行升级：通过插件设置中的"Check for Updates"自动升级
- 手动更新：运行命令
cd ComfyUI && git pull && pip install -r requirements.txt
错误E301：Python依赖冲突
错误描述：ModuleNotFoundError: No module named 'torchvision'
可能原因：Python虚拟环境依赖未正确安装。
解决步骤：
- 重建虚拟环境：删除
ai_diffusion/venv目录后重启插件 - 手动安装依赖：
cd ai_diffusion && python -m venv venv && source venv/bin/activate pip install -r server_requirements.txt - 检查Python版本：确保使用Python 3.10-3.12版本
硬件资源错误
硬件相关错误主要涉及GPU内存不足、CUDA驱动问题，相关代码位于ai_diffusion/server.py和ai_diffusion/connection.py。
错误E400：GPU内存不足
错误描述：OutOfMemoryError: CUDA out of memory
可能原因：生成分辨率过高或GPU显存不足。
解决步骤：
- 降低生成分辨率：在插件设置中将分辨率调整为512x512或更低
- 调整性能设置：在ai_diffusion/settings.py中设置
performance_preset为"low" - 关闭其他GPU应用：确保关闭其他占用GPU资源的程序
图3：性能预设调整界面
错误E401：CUDA驱动未安装
错误描述：CUDA driver initialization failed
可能原因：NVIDIA显卡驱动未安装或版本过低。
解决步骤：
- 检查驱动版本：执行
nvidia-smi命令确认驱动状态 - 更新驱动：从NVIDIA官网下载安装对应型号的最新驱动
- 切换后端：在插件设置中将
server_backend改为"cpu"（性能会降低）
配置文件错误
配置文件错误通常由JSON格式错误或参数值非法导致，主要涉及ai_diffusion/settings.py和ai_diffusion/presets/目录下的JSON文件。
错误E500：配置文件损坏
错误描述：JSONDecodeError: Expecting property name enclosed in double quotes
可能原因：设置文件config.json格式错误。
解决步骤：
- 验证JSON格式：使用在线工具（如JSONLint）检查文件语法
- 重置配置：删除
~/.config/krita-ai-diffusion/config.json后重启插件 - 手动恢复：从备份或presets/models.json复制默认配置
错误E501：非法参数值
错误描述：ValueError: Invalid resolution: 0 (must be between 256 and 4096)
可能原因：生成分辨率设置为0或超出有效范围。
解决步骤：
- 检查配置值：打开ai_diffusion/settings.py确认
default_resolution设置 - 修复参数：确保分辨率值在256-4096范围内
- 重置默认值：在插件设置中点击"Restore Defaults"
其他常见错误
错误E999：未知错误
错误描述：Unknown error occurred: [exception details]
可能原因：未归类的异常或新问题。
解决步骤：
- 查看详细日志：
~/.local/share/krita-ai-diffusion/client.log - 检查版本兼容性：确认插件版本与Krita版本匹配（Krita 5.2+）
- 提交Issue：在项目仓库提交错误报告，附带日志信息
图4：错误日志文件内容示例
错误排查工具
日志文件位置
- 客户端日志：
~/.local/share/krita-ai-diffusion/client.log - 服务器日志：
~/.local/share/krita-ai-diffusion/server.log - 安装日志：
~/.local/share/krita-ai-diffusion/install.log
系统检查命令
# 检查Python环境
python -m ai_diffusion.util --check-env
# 验证资源完整性
python scripts/verify_resources.py
# 生成系统信息报告
python scripts/system_info.py
总结与支持
本手册涵盖了Krita-AI-Diffusion的六大类常见错误，通过错误代码可快速定位问题根源。若按手册步骤仍无法解决问题，可通过以下方式获取支持：
- 查阅官方文档：docs/README.md
- 社区支持：Krita论坛AI插件板块
- 项目Issue：提交错误报告
定期更新插件和依赖库可有效减少错误发生，建议开启自动更新功能。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
