跳到主要内容

系统、性能与服务报错

本页整理归位通信超时、MCU 定时错误、上位机性能、固件刷写和 Klipper 服务启动相关问题。

归位超时问题​

报错信息：归位过程中出现 Communication timeout during homing、Error during homing xxx。常见于多 MCU 的 Z 轴归位场景。

常见原因：

  • 上位机负载过高，KlipperScreen、摄像头流等同时运行。
  • 归位时多轴电机同时运动，大电流驱动信号耦合到 CAN/USB 通信线，导致通信中断。
  • 多 MCU 通信响应不稳定。
  • CAN/USB 通信线质量问题或走线不当。

解决方法：

断电操作

重新整理 CAN/USB 走线、检查屏蔽层或检查接地前，请完全关闭打印机并断开电源供应。不要自行改动电源地线、市电接线或电源内部结构。

  1. 首先排除电磁干扰：检查 CAN/USB 线是否与电机线、加热线分离走线，参考 CAN 网络配置与 ID 搜索 中的干扰排查步骤。
  2. 尝试调整 TRSYNC_TIMEOUT 超时参数或临时关闭 KlipperScreen，详见 归位超时问题。
  3. 检查机器接地和屏蔽层接地是否正常。

MCU 'mcu' shutdown: Stepper too far in past​

报错信息：Klipper 计划发送给 MCU 的步进事件已经落后于当前时间，MCU 无法再按预期时间执行这些运动指令，打印机会进入 shutdown 状态。

Loading...

报错原因：这通常不是某一个固定配置项导致，而是主机端运动规划、MCU 步进输出或通信调度来不及处理造成的结果。上位机负载过高、打印速度/加速度过高、步进细分过高、多 MCU 通信延迟、USB / CAN 通信质量差、宏或 G-code 短时间生成大量运动指令，都可能触发该问题。

参考场景：执行多点扫床时，如果 [bed_mesh] 中的 probe_count 设置过大，并且同时配置了较高的 mesh_pps，可能会生成过密的网格数据，增加上位机计算和运动规划压力。这只是常见场景之一；即使没有扫床，其他导致系统负载或通信延迟升高的情况也可能出现 Stepper too far in past。

解决方法：

  1. 先查看 klippy.log 中报错前的 Stats 行，确认是否同时存在 CPU 占用高、bytes_retransmit、bytes_invalid、Timer too close、MCU 掉线或队列异常。
  2. 临时关闭摄像头流、KlipperScreen、远程控制插件和其他高占用服务，降低上位机负载后复测。
  3. 降低打印速度、加速度和步进细分，观察报错是否消失。
  4. 如果报错出现在多点扫床过程中，可降低 [bed_mesh] 中的 probe_count，例如改为 7,7 或 9,9 测试。
  5. 如果配置了较高的 mesh_pps，可降低或删除该配置，例如改为 mesh_pps: 2,2。
  6. 检查 USB / CAN 通信质量；如果使用 CAN，确认队列长度、终端电阻、线序、供电和固件 CAN 速率。
  7. 检查触发报错前正在执行的宏或 G-code，避免宏循环、过密短线段或异常脚本短时间发送大量运动命令。

相关配置参考：宏介绍、常用调试指令。

MCU 'mcu' shutdown: Timer too close​

报错信息：MCU 计时器过于接近，导致系统超时。

Loading...

报错原因：下位机处理负载过高、上位机响应超时、打印速度过高、细分过高、系统时间同步干扰或 MCU 通信线受到干扰，都可能触发该问题。

解决方法：

  1. 降低步进电机细分，减少 MCU 脉冲处理压力。
  2. 降低打印速度和加速度，观察问题是否消失。
  3. 检查上位机负载、供电和 USB / CAN 通信质量。
  4. 断电后检查 MCU 与上位机之间的通信线是否靠近电机线、加热线、热床线或电源线，必要时重新走线或更换带屏蔽的通信线。
  5. 检查机器接地情况时，仅确认厂家提供的接地点和插座状态，不要自行拆卸电源或改动市电地线。
  6. 如果问题发生在归位阶段，请参考 归位超时问题。
  7. 如果问题持续存在，再考虑重新刷写上位机系统或固件。

相关配置参考：常用调试指令、归位与方向校准指南。

MCU shutdown: Missed scheduling of next digital out event​

报错信息：MCU 'xxx' shutdown: Missed scheduling of next digital out event。

报错原因：Klipper 主机端打开加热器、风扇等数字输出后，MCU 需要按时收到后续调度和确认。如果上位机负载过高、系统调度延迟、USB / CAN 通信不稳定，或 CAN 总线队列异常，MCU 没有及时收到下一次数字输出事件，就会进入 shutdown 状态。

注意

该报错与加热器输出调度有关。不要通过关闭温度保护、关闭 verify_heater 或删除安全配置来绕过报错，应先排查上位机负载和通信质量。

解决方法：

  1. 先查看 klippy.log 中该报错前面的 Stats 行，确认是否同时存在 bytes_retransmit、bytes_invalid、Timer too close 或 MCU 掉线记录。
  2. 降低上位机负载，临时关闭摄像头流、KlipperScreen、远程控制插件或其他高占用服务。
  3. 检查 USB / CAN 通信质量；如果使用 CAN，确认 CAN0 队列长度、终端电阻、线序、供电和固件 CAN 速率。
  4. 降低打印速度、加速度和步进细分，观察问题是否消失。
  5. 如果只在加热时出现，同时检查热床、热端、风扇和电源负载；不要自行拆解电源或检查市电热床高压接线。
  6. 如果问题发生在 CAN 工具板上，按 CAN 报错排查 继续处理。

相关配置参考：常用调试指令、CAN 网络与 ID 搜索。

Rescheduled timer in the past​

报错信息：日志中出现 Rescheduled timer in the past 或类似警告。

报错原因：上位机系统时钟问题或 CPU 负载过高，导致定时任务实际执行时间落后于计划时间。

解决方法：

  1. 如果启用了 NTP 同步，临时关闭测试。
  2. 降低上位机运行的其他服务负载，如关闭不必要的 Web 界面、摄像头流等。
  3. 如果在虚拟机中运行，考虑迁移到物理机或使用更稳定的时钟源。
  4. 检查上位机 CPU 使用率：htop 查看 klippy 进程是否有异常 CPU 占用。

相关配置参考：常用调试指令。

Internal error on command​

报错信息：Internal error on command:"XXX"，Klipper 进入 shutdown 状态。

常见原因：

  • 宏或 G-code 命令触发了 Klipper 内部 Python 异常。
  • 配置文件中存在错误的宏引用或 Jinja2 模板语法错误。
  • Klipper 版本与配置文件格式不兼容。
  • G-code 文件名包含特殊字符导致编码错误。

解决方法：

  1. 查看 klippy.log 中 Internal error 下方的完整 Python Traceback。
  2. 根据 Traceback 定位是哪个配置文件或宏出现了问题。
  3. 常见原因包括 [gcode_macro] 中 Jinja2 模板语法错误、[respond] 配置缺失、[virtual_sdcard] 路径错误。
  4. 如果报错与 SDCARD_PRINT_FILE 相关且提示 ascii codec can't decode，请将 G-code 文件名改为英文、数字、下划线或短横线。

相关配置参考：宏介绍、配置修改说明。

Unable to open file / SD busy​

报错信息：打印文件时提示 Unable to open file、Unable to get file list、SD busy、SD write not supported、SDCARD_RESET_FILE cannot be run from the sdcard。

常见原因：

  • G-code 文件不存在、文件名被改动或上传未完成。
  • [virtual_sdcard] path 指向错误目录。
  • 文件权限异常，Klipper 用户无法读取。
  • 文件名包含特殊字符，导致某些前端或系统路径处理异常。
  • 正在打印或正在读取文件时，又执行了打开、选择、重置或写入虚拟 SD 的命令。
  • 将 Klipper 源码目录、配置目录或其他非 G-code 目录误写成 [virtual_sdcard] path。

解决方法：

  1. 在网页端重新上传一次 G-code 文件，并确认文件名与打印命令一致。
  2. 检查 [virtual_sdcard] path 是否指向实际 G-code 存放目录。
  3. 检查目录权限：ls -la ~/printer_data/gcodes/。
  4. 将文件名改为英文、数字、下划线或短横线后再测试。
  5. 如果提示 SD busy，先暂停或取消当前打印，确认没有其他宏正在操作虚拟 SD 文件。
  6. 不要把 ~/klipper、~/printer_data/config 或系统目录设置为 G-code 存放目录。

相关配置参考：配置修改说明。

MCU CRC does not match config / Can not update MCU config​

报错信息：MCU 'xxx' CRC does not match config、Can not update MCU 'xxx' config as it is shutdown、Unable to configure MCU 'xxx'。

判断重点：Can not update MCU 'xxx' config as it is shutdown 通常不是最初根因，而是 MCU 已经处于 shutdown/error 状态后，Klipper 再次连接或重新配置 MCU 时出现的后续报错。排查时不要只看日志最后一行，应向上翻找更早的第一条真实报错。

解决方法：

  1. 执行 FIRMWARE_RESTART，必要时整机断电 10 秒后重新上电。
  2. 查看 klippy.log 中更早出现的第一条 shutdown、Timer too close、Lost communication、Verify heater、TMC 或温度报错，先修复导致 shutdown 的根因。
  3. 多 MCU 机器逐个检查 [mcu]、[mcu xxx] 的 USB ID 或 CAN UUID。
  4. 如果刚更新过 Klipper，重新编译并刷写全部 MCU 固件。
  5. 如果使用 [mcu host]，检查 klipper-mcu 服务是否正常启动，再重启 Klipper。
  6. 如果使用预装或定制 Klipper 系统，确认日志完整、Klipper 和 MCU 固件版本来源一致。

Shutdown due to M112 command / webhooks request​

报错信息：Shutdown due to M112 command 或 Shutdown due to webhooks request。

解决方法：

  1. 确认是否人为点击了急停；若是，排除风险后执行 FIRMWARE_RESTART。
  2. 在自定义宏中搜索 M112、action_emergency_stop、emergency_stop。
  3. 检查前端、远程控制插件或自动化脚本是否误触发急停接口。

上位机性能不足导致打印卡顿​

报错信息：无明显错误，但打印过程中出现间歇性停顿、挤出断续。

解决方法：

  1. 降低打印速度和加速度。
  2. 关闭上位机上不必要的 Web 服务、摄像头流等。
  3. 减少 [bed_mesh] 的 probe_count 和 mesh_pps。
  4. 如果切片器输出了 G2 / G3 圆弧，参考 圆弧拟合建议 调整或关闭。
  5. 如果上位机性能确实不足，考虑更换性能更强的上位机。

上位机异常重启 / 系统崩溃​

报错信息：打印中 Klipper / Moonraker 突然断开，klippy.log 突然中断，没有明确 shutdown 根因；Mainsail / Fluidd 重新连接后发现上位机或 Klipper 已重启。

常见原因：

  • 上位机供电不足，打印过程中 USB、摄像头、屏幕或风扇负载变化导致掉电。
  • 系统盘、TF 卡或 eMMC 读写异常，日志突然中断或文件损坏。
  • 上位机 CPU 过热，系统保护性降频、卡死或重启。
  • USB 反供电或外设供电路径异常，导致主板、屏幕或上位机互相影响。
  • 第三方服务、摄像头流、AI 插件或过多网页连接占用资源。

排查方法：

断电操作

检查上位机供电线、USB 线、屏幕线、风扇线或整理走线前，请完全关闭打印机并断开电源供应。不要拆解电源或改动市电接线。

  1. 先查看 klippy.log、moonraker.log 和系统日志，确认是 Klipper 报错还是整机上位机重启。
  2. 检查上位机电源规格，避免使用电流不足或压降明显的电源线。
  3. 检查系统盘健康状态，必要时更换可靠 TF 卡、eMMC 或重新刷写系统。
  4. 检查上位机散热，确认风扇正常、散热片贴合、外壳通风。
  5. 临时关闭摄像头流、KlipperScreen、远程控制插件和其他高负载服务后再打印测试。
  6. 如果怀疑 USB 反供电，优先更换成品 USB 线或使用带电源隔离的连接方案，普通用户不要自行改线。

暂停、恢复与状态保存提示​

报错信息：Print already paused、Print is not paused, resume aborted、Unknown g-code state: PAUSE_STATE。

常见原因：

  • 重复执行 PAUSE，或打印已经取消后又执行 RESUME。
  • 自定义暂停/恢复宏中 SAVE_GCODE_STATE NAME= 与 RESTORE_GCODE_STATE NAME= 名称不一致。
  • 第三方宏包与 Mainsail / Fluidd 默认暂停恢复宏重复定义或逻辑冲突。
  • 急停、FIRMWARE_RESTART 或 Klipper 报错后，原来的暂停状态已经丢失。

解决方法：

  1. 确认当前打印状态，不要在未暂停时执行 RESUME。
  2. 检查 [pause_resume] 是否启用，以及 PAUSE / RESUME / CANCEL_PRINT 宏是否重复定义。
  3. 检查宏中的 SAVE_GCODE_STATE 和 RESTORE_GCODE_STATE 名称是否完全一致。
  4. Klipper 已报错或急停后，不建议继续恢复打印，应排除风险后重新开始。

Klipper 反复重启（Klippy not connected 反复闪烁）​

报错信息：Mainsail / Fluidd 显示 Klippy not connected 反复出现，Klipper 不断自动重启且每次都在几秒内退出。日志中可能看到 Klipper restarting too fast 或每次重启的 klippy.log 很短。

排查方法：

  1. 先查看日志文件末尾，确认最后一次退出的原因：

    tail -100 ~/printer_data/logs/klippy.log

  2. 如果日志末尾是 Python Traceback，表示是配置解析或内部异常导致的崩溃。

  3. 不要只根据 Klipper restarting too fast 判断根因；它通常只是 systemd 反复拉起失败后的结果，应优先处理 klippy.log 中第一条真实错误。

  4. 如果日志末尾显示 MCU Protocol error、Unknown command 等，说明固件版本不匹配，需要重新编译刷写 MCU 固件。

  5. 如果日志很短且无明显错误，尝试用最小化配置二分法定位。

  6. 检查 include 文件中是否存在循环引用。

Loading...