跳到主要内容

系统、性能与服务报错

本页整理归位通信超时、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。

恢复打印后停滞场景：报错也可能出现在 PAUSE / RESUME、断料恢复或断电续打之后。典型日志表现为：恢复后 Stats 行的 buffer_time 从约 1s 骤降到 0.2s 左右，sd_pos 几乎不再增长（打印进度停滞），但 sysload 并不高、也没有 MCU 掉线。这说明恢复后运动指令未能持续填充步进缓冲区，打印机“开打了但没怎么动”就进入 shutdown。排查时重点检查恢复 / 续打宏（resume_gcode、start_gcode）是否在恢复瞬间发送了异常的大段移动或回抽指令，以及恢复前是否已存在通信重传（bytes_retransmit 增长）。

解决方法：

  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 通信线受到干扰，都可能触发该问题。

近期常见场景：

  • M600、PAUSE、RESUME、断料检测或换料宏等待一段时间后恢复打印，随后触发 Timer too close。
  • EDDY / TAP / CAN 工具板参与 Z 归位、Z_TILT_ADJUST、QUAD_GANTRY_LEVEL 或扫床时，日志中同时出现 CAN 重传、I2C 读数异常或上位机负载尖峰。
  • 多工具头、多 CAN 节点或低性能上位机同时运行摄像头、KlipperScreen、远程控制插件时，调度余量不足。

解决方法：

  1. 降低步进电机细分，减少 MCU 脉冲处理压力。
  2. 降低打印速度和加速度，观察问题是否消失。
  3. 检查上位机负载、供电和 USB / CAN 通信质量。
  4. 断电后检查 MCU 与上位机之间的通信线是否靠近电机线、加热线、热床线或电源线，必要时重新走线或更换带屏蔽的通信线。
  5. 检查机器接地情况时，仅确认厂家提供的接地点和插座状态，不要自行拆卸电源或改动市电地线。
  6. 如果问题发生在归位阶段，请参考 归位超时问题。
  7. 如果发生在 M600 或断料恢复后，检查宏中是否重复 PAUSE、断料传感器是否在换料过程中误触发，以及 SAVE_GCODE_STATE / RESTORE_GCODE_STATE 名称是否一致。
  8. 如果发生在 EDDY TAP、Z 倾斜或龙门调平时，先参考 EDDY TAP 模式调试方法。
  9. 如果问题持续存在，再考虑重新刷写上位机系统或固件。

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

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 占用。

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

MCU 'mcu' shutdown: Move queue overflow​

报错信息：MCU 'mcu' shutdown: Move queue overflow。

报错原因：MCU 运动队列被填满，主机端没有及时把运动规划和状态同步到 MCU。常见于主机性能不足、短时间内大量细碎移动、Klipper 主机端与 MCU 固件版本不一致，或厂商定制 Klipper 在每个移动命令中加入同步写盘、断电续打等阻塞逻辑。

常见判断点：

  • klippy.log 中 Git version 与 Loaded MCU 'xxx' ... version 基础版本差距较大。
  • 日志出现 dirty、第三方 klippy/extras 文件、厂商定制断电续打或非官方 Klipper。
  • 同一个 G-code 文件在相近位置失败，且模型包含大量短线段、密集支撑、螺旋 Z-hop 或复杂路径。
  • 低性能上位机同时运行摄像头、屏幕、远程控制或其他高负载服务。

解决方法：

  1. 查看完整 klippy.log，先确认是否还有更早的 Timer too close、CAN 掉线、bytes_invalid 或温度/TMC 报错。
  2. 更新 Klipper 后，重新编译并刷写全部 MCU 固件，确保上位机与主板、工具板固件版本一致。
  3. 临时关闭摄像头流、KlipperScreen、远程控制插件和其他高占用服务后复测。
  4. 降低打印速度、加速度、步进细分，或在切片器中降低曲线精度、支撑复杂度和短线段密度。
  5. 如果使用厂商定制断电续打、自动高度记录或第三方插件，先用原版 Klipper 或关闭对应功能交叉测试；不要直接修改 Klipper 源码给普通客户作为常规步骤。
  6. 如果只发生在某个 G-code 文件，重新切片并检查切片器是否输出异常密集路径。

相关配置参考：常用调试指令、圆弧拟合建议。

stepcompress / syncemitter / flush_handler 内部错误​

报错信息：stepper.error: Internal error in stepcompress、stepcompress ... Invalid sequence、Error in syncemitter 'extruder' step generation、Exception in flush_handler、Flush Handler error。

报错原因：Klipper 在生成或压缩步进脉冲时遇到内部异常。近期社区案例中，这类问题常与高速扫床、scanner / EDDY / Cartographer 类探针插件、input_shaper、复杂运动路径或第三方 Klipper 修改同时出现。它不一定是切片器单独导致，也不应只靠重新切片判断根因。

解决方法：

  1. 保留完整 klippy.log，重点查看该报错前后的 Python Traceback、正在执行的命令和 Stats 行。
  2. 如果报错发生在 BED_MESH_CALIBRATE、QUAD_GANTRY_LEVEL 或 scanner 扫床时，先降低扫床速度、点数、插值密度和插件扫描参数。
  3. 临时禁用第三方 scanner、自动调速、自动调平增强、宏包或厂商修改，使用原版 Klipper 复测。
  4. 更新 Klipper 后重新刷写全部 MCU 固件，并确认外设固件与主机 Klipper 版本匹配。
  5. 如果同一模型反复触发，重新切片并降低短线段密度；若重新切片后仍随机出现，应继续按主机负载、运动参数和插件兼容性排查。
  6. 如果打印机出现异常运动、丢步或撞车风险，应立即急停并重新归位，不要继续恢复原任务。

相关配置参考：运动、限位与调平报错、EDDY 问题合集。

Internal error on command​

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

常见原因：

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

解决方法：

  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 文件名改为英文、数字、下划线或短横线。
  5. 如果 Traceback 中出现 stepcompress、syncemitter 或 flush_handler，请按 stepcompress / syncemitter / flush_handler 内部错误 继续排查。

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

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 固件版本来源一致。

MCU 'xxx' shutdown: Command request​

报错信息：MCU 'xxx' shutdown: Command request。

常见原因：

  • CAN 工具板固件版本与上位机 Klipper 版本不匹配，上位机发送了该固件不支持的命令。
  • 更新 Klipper 或系统后未重新编译刷写工具板固件。
  • 配置了该 MCU 固件未编译支持的功能（如未启用 I2C 却配置了 EDDY / ADXL）。

解决方法：

  1. 查看 klippy.log 中 Loaded MCU 'xxx' ... version 与 Git version，确认版本是否一致。
  2. 重新编译并刷写报错 MCU 的固件，刷写方式以对应工具板产品文档为准。
  3. 多 MCU 机器应确保所有 MCU 固件来自同一次编译。
  4. 刷写完成后执行 FIRMWARE_RESTART，确认不再报错。

通用版本排查：MCU Protocol error

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 文件中是否存在循环引用。

Unhandled exception during run​

报错信息：Unhandled exception during run，前端显示 Printer is shutdown，日志中伴随 Python Traceback。

常见原因：

  • 这不是一个独立的硬件故障，而是 Klipper 主循环捕获到未处理异常后的通用报错。真实原因需要看 Traceback 上方的具体错误。
  • 常见触发源：TMC UART 读取失败（Unable to read tmc uart 'stepper_x' register DRV_STATUS）、CAN 通信中断、宏模板运行时错误、第三方扩展模块异常。
  • 升级 Klipper 后旧配置或旧宏与新版本 API 不兼容。
  • 上位机 Python 环境损坏或依赖缺失。

解决方法：

  1. 打开完整 klippy.log，搜索 Unhandled exception during run 上方的 Traceback，找到第一条真实报错（如 Unable to read tmc uart、CanError、TypeError 等）。
  2. 如果真实报错是 TMC UART 通信失败，按 TMC 报错排查 检查接线和配置。
  3. 如果是 CAN 通信异常，按 CAN 报错排查 检查总线状态。
  4. 如果 Traceback 指向某个宏或扩展模块，检查该模块是否与当前 Klipper 版本兼容，必要时更新或临时禁用。
  5. 升级 Klipper 后出现此报错，检查 Config_Changes.md 中是否有配置迁移要求。
  6. 不要只根据 Unhandled exception during run 这一行判断问题，它只是外壳，真因始终在 Traceback 中。

Missed scheduling of next hard pwm event​

报错信息：MCU 'mcu' shutdown: Missed scheduling of next hard pwm event。

常见原因：

  • 与 Missed scheduling of next digital out event 同类，均为上位机未能在截止时间内将 PWM 事件下发到 MCU。
  • 上位机 CPU 负载过高（摄像头流、KlipperScreen、大量插件同时运行）。
  • 使用激光模块或高频 PWM 工具时，cycle_time 设置过小导致调度间隔极短。
  • CAN 总线延迟过高，事件在传输中超时。

解决方法：

  1. 检查上位机 CPU 负载，临时关闭摄像头、KlipperScreen 和其他非必要服务后复测。
  2. 如果使用激光或 PWM 工具，适当增大 cycle_time（例如从 0.00002 改为 0.0001）。
  3. 检查 CAN 总线状态，确认 tx_error、bytes_retransmit 没有持续增长。
  4. 更换高质量 USB 线或降低 CAN 波特率（从 1M 降到 500K）测试。
  5. 低性能上位机（旧手机、低端开发板）建议精简同时运行的服务数量。

相关报错：Missed scheduling of next digital out event

Can't reset time when stepper active​

报错信息：MCU 'mcu' shutdown: Can't reset time when stepper active，常伴随打印中途 Klipper 自动重启；重启后可能紧接着出现 TMC stepper_x failed to init: Timeout on wait for 'tmcuart_response' response。

常见原因：

  • 这不是独立的硬件故障，而是上位机在步进电机仍在运动时尝试重置步进时钟基准，MCU 拒绝并进入 shutdown 保护。
  • 最常见触发源是 Klipper 服务在打印中途自发重启（上位机侧）：日志中会看到 Starting Klippy... 紧跟在上一秒还在打印的 Stats 统计行之后。
  • 通过 Moonraker 连接的某个客户端或插件反复请求重启服务。
  • 上位机供电不足、过热、内存耗尽等导致系统把 klipper 服务杀死后重新拉起。

解决方法：

  1. 打开完整 klippy.log，搜索 Starting Klippy...，确认 Klipper 是否在打印中途重启，以及与上一条打印统计行的时间间隔。
  2. 执行 systemctl status klipper.service 和 journalctl -efu klipper，查看服务被重启的记录与原因。
  3. 检查 Moonraker 连接的客户端与插件（摄像头流、第三方插件、自定义脚本），确认没有设备在请求重启服务或重启机器。
  4. 检查上位机供电、散热与内存占用，老旧树莓派或低性能开发板同时运行摄像头和 KlipperScreen 时容易因内存不足被系统杀死。
  5. 重启后出现的 Timeout on wait for 'tmcuart_response' 是重启的结果而非根因，不要因此先排查 TMC 接线。

相关报错：Klipper 反复重启、Unhandled exception during run

Loading...