跳到主要内容

常见报错提示

本页用于快速定位 Klipper 常见报错。请先在 klippy.log 找到完整报错，再查看对应说明。

连接问题​

mcu 'xxx': Unable to connect​

报错信息：上位机无法找到或连接到主板。

Loading...

常见原因：

  • USB 设备 ID 未填写或填写错误。
  • CAN UUID 未填写、填写错误或设备未在线。
  • UTOC、USB 线、CAN 桥接固件或供电异常。
  • CAN0 未启动，或 CAN 网络配置异常。

处理方法：

  1. 打开 klippy.log 并翻到最下方，确认具体错误信息。

  2. 如果出现 [Errno 2]，通常表示没有将搜索到的 USB 设备 ID 添加到 printer.cfg。

    Loading...

  3. 如果出现 Serial connection closed，通常需要重新搜索 CAN ID 并检查 CAN 网络。

    Loading...

  4. 如果出现 Unable to open CAN port: [Errno 19] No such device，通常表示缺少 UTOC 设备、USB 桥接 CAN 固件或 CAN0 设备。

    Loading...

  5. 如果出现 [Errno 100] Network is down 或 [Errno 105] No buffer space available，请按 CAN 网络与 ID 搜索 重新检查 CAN0 配置。

mcu 'mcu': Invalid CAN uuid​

报错信息：CAN UUID 无效或无法识别。

Loading...

报错原因：canbus_uuid: 填写错误、设备不在线，或 CAN 网络未正常通信。

解决方法：

  1. 按 CAN 网络与 ID 搜索 重新搜索 CAN UUID。
  2. 确认 printer.cfg 中填写的是实际搜索到的 UUID。
  3. 确认同一个 [mcu] 中没有同时启用 serial: 和 canbus_uuid:。
  4. 检查 CAN-H、CAN-L、终端电阻、供电和固件 CAN 速率。

Option 'serial' in section 'mcu' must be specified​

报错信息：在 [mcu] 配置段中必须指定 serial。

Loading...

报错原因：USB 固件连接时没有填写 serial:，或者 [mcu] 配置段被误删。

解决方法：

  1. 重新搜索 USB 设备 ID。
  2. 在 printer.cfg 的 [mcu] 配置段中填写：
[mcu]
serial: /dev/serial/by-id/实际搜索到的ID
  1. 保存并重启 Klipper。

如果当前主板刷写的是 CAN 固件，请使用 canbus_uuid:，不要继续填写 serial:。

Lost communication with MCU​

报错信息：Klipper 与 MCU 通信中断，日志中可能出现 Lost communication with MCU、Lost communication with mcu 或类似提示。

常见场景：归位或移动过程中，限位开关一触发，主板或工具板就掉线；重新上电后又能连接。

常见原因：

  • 限位开关接线错误，触发时造成信号脚与电源或地异常短接。
  • 使用三线限位、光电限位或霍尔限位时，电源、地线、信号线顺序接错。
  • 限位线束破皮、压线或拖链运动时短路。
  • 限位触发瞬间导致主板供电波动，MCU 重启或 USB / CAN 通信中断。
  • MCU 与上位机之间的 USB / CAN 通信线经过强干扰源，触发限位或运动时更容易出现掉线。
  • 配置中的限位引脚与实际接线不一致，触发了错误的接口。

排查方法：

  1. 断电后检查限位开关线序，特别是三线限位的 VCC、GND、Signal 是否接反。
  2. 暂时拔掉对应限位线，再重新上电测试主板是否还会掉线。
  3. 使用万用表检查限位触发前后是否存在短路，重点检查信号脚是否被接到电源。
  4. 检查拖链、接插件和线束弯折位置，确认触发或移动时不会压线短路。
  5. 检查 MCU 与上位机之间的 USB / CAN 通信线，尽量避开电机线、加热线、热床线和电源线。
  6. 如果机器外壳、电源或屏蔽层未可靠接地，也可能更容易受到干扰，请按设备电气安全要求检查接地。
  7. 确认配置中的限位引脚与主板文档、实际接线一致。
  8. 问题修复后再执行 QUERY_ENDSTOPS，确认限位状态能正常从 open 变为 TRIGGERED。

MCU Protocol error​

报错信息：MCU 协议错误，日志中可能出现 MCU Protocol error、Unknown command 或 Command format mismatch。

Loading...

常见原因：

  • 更新了上位机 Klipper，但没有重新编译并刷写主板或工具板固件。
  • 主板、工具板、EDDY、ADXL 等外设 MCU 的固件版本与上位机 Klipper 不匹配。
  • 使用了定制系统或第三方插件，导致 Klipper 主机端与 MCU 支持的命令不一致。

解决方法：

  1. 确认最近是否更新过 Klipper、系统镜像或插件。
  2. 重新编译并刷写对应 MCU 的 Klipper 固件。
  3. 如果是工具板、EDDY、ADXL 等外设 MCU，请同步更新对应外设固件。
  4. 如果使用定制系统，请确认该系统支持当前 Klipper 版本。
  5. 刷写完成后执行 FIRMWARE_RESTART，再重新连接测试。

配置冲突问题​

homing override method always homes X and Y before homing Z. The safe_z_home​

报错信息：安全 Z 归位与归位覆盖配置冲突。

Loading...

报错原因：同时配置了 [safe_z_home] 和 [homing_override]，导致 Klipper 无法确认使用哪套归位逻辑。

解决方法：

  1. 在配置文件中搜索 [safe_z_home] 和 [homing_override]。
  2. 根据机器实际归位逻辑只保留其中一项。
  3. 保存并重启 Klipper。

运动与归位问题​

Move out of range​

报错信息：目标坐标超出 Klipper 允许的运动范围，日志中通常会显示类似 Move out of range: X Y Z [E]。

Loading...

常见原因：

  • 切片机中的机器尺寸与 Klipper 配置中的 position_min / position_max 不一致。
  • 起始 G-code、结束 G-code、换料宏或暂停宏移动到了机器范围外。
  • M600、PAUSE、CANCEL_PRINT 等宏的停靠位置太靠近边界。
  • 使用偏斜校正、探针偏移或网床配置后，实际计算坐标变成负值或超过最大行程。
  • 模型高度超过 Z 轴最大行程。

解决方法：

  1. 根据报错中的坐标判断是哪一个轴超出范围。
  2. 检查对应轴的 position_min、position_max 和切片机机器尺寸。
  3. 检查起始、结束、暂停、换料等宏中的停靠坐标，避免停在 0,0 或最大边界。
  4. 如果报错发生在扫床时，检查 [bed_mesh] 的 mesh_min、mesh_max 和探针偏移。
  5. 保存配置并重启 Klipper 后重新测试。

Must home axis first​

报错信息：轴尚未归位，不能执行当前移动命令。

常见原因：

  • 开机或 FIRMWARE_RESTART 后没有执行 G28。
  • 宏中先执行了移动命令，再执行归位命令。
  • 打印暂停、恢复或取消后，机器状态被重置。
  • 归位宏、探针宏或无限位归位配置异常，导致 Klipper 没有正确记录已归位状态。

解决方法：

  1. 手动执行 G28 后再移动对应轴。
  2. 检查起始 G-code 和宏，确认移动命令前已经完成归位。
  3. 如果刚更新过 Klipper 或固件，检查归位相关宏是否仍兼容当前版本。
  4. 如果使用无限位归位，检查驱动电流、灵敏度和 homing_retract_dist。

Endstop still triggered after retract​

报错信息：归位触发限位后，回退距离结束时限位仍然处于触发状态。

常见原因：

  • 限位开关常开/常闭逻辑配置反了。
  • 限位开关卡住、损坏或线序错误。
  • homing_retract_dist 太小，回退后仍压着限位。
  • 无限位归位灵敏度过高，回退后仍被判断为触发。
  • 驱动 enable_pin、电机方向或限位引脚配置错误，导致归位动作不正常。

解决方法：

  1. 执行 QUERY_ENDSTOPS，确认未触发时为 open，手动触发后为 TRIGGERED。
  2. 如果状态相反，调整限位引脚前的 !。
  3. 检查限位开关机械状态、线序和插头。
  4. 适当增加 homing_retract_dist 后重新测试。
  5. 如果使用无限位归位，降低灵敏度并确认归位电流合适。

No trigger on probe after full movement​

报错信息：探针在完整下探行程内没有触发。

常见原因：

  • 探针接线、供电或引脚配置错误。
  • 探针安装高度不合适，下探行程内无法触发。
  • Z 轴方向、探针偏移或调平区域配置错误。
  • 探针本体故障，或线束在移动时接触不良。
  • 热床、喷嘴或探针位置超出可探测范围。

解决方法：

  1. 执行 QUERY_PROBE，手动触发探针，确认状态能正常变化。
  2. 检查探针供电、信号线和配置引脚。
  3. 检查探针安装高度，确认下探前探针处于可触发范围。
  4. 检查 [probe]、[bed_mesh]、[z_tilt] 或 [quad_gantry_level] 中的探测点是否超出热床。
  5. 如果问题只在某些位置出现，重点检查线束拖动和探针偏移。

温度检测问题​

Error 'XXX mcu' shutdown: ADC out of range​

报错信息：ADC 超出量程范围，温度检测异常。

Loading...

报错原因：Klipper 检测到温度超过配置允许范围，常见于热敏电阻开路、短路、接线错误、热敏型号配置错误或引脚配置错误。

注意

临时放宽 min_temp 和 max_temp 只能用于排查，不能作为长期配置。确认问题后必须恢复到安全范围，避免温度保护失效。

排查顺序：

  1. 检查热敏电阻是否插牢，线材是否断裂或短路。
  2. 检查热敏型号和引脚配置是否与实际硬件一致。
  3. 必要时临时放宽温度范围用于确认读数变化，例如将 min_temp 改低、max_temp 改高。
  4. 找到并解决接线或配置问题后，立即恢复原来的安全温度限制。
  5. 保存并重启 Klipper。

Heater not heating at expected rate​

报错信息：加热器没有按预期速度升温，日志中可能出现 Heater extruder not heating at expected rate 或 Heater heater_bed not heating at expected rate。

Loading...

常见原因：

  • 加热棒、热床或 SSR / MOS 管输出异常。
  • 热敏电阻接触不良、线材半断或读数跳变。
  • 风扇直吹热端、热床或加热区域，导致升温过慢。
  • 热床功率不足，或 max_power 限制过低。
  • PID 参数不合适，温度接近目标时波动过大。

解决方法：

  1. 检查加热器和热敏电阻接线是否牢固。
  2. 观察温度曲线，确认升温是否连续、是否有异常跳变。
  3. 检查是否有风扇直吹热端或热床。
  4. 检查加热器功率、供电、保险丝、SSR / MOS 管和 max_power 设置。
  5. 确认硬件正常后重新执行 PID 校准。
  6. 如果确认只是大尺寸热床或特殊结构导致升温慢，可参考 verify_heater 优化。

挤出问题​

Extrude below minimum temp​

报错信息：喷嘴温度低于允许挤出的最低温度，日志中可能出现 Extrude below minimum temp 或 Extruder not hot enough。

常见原因：

  • 未加热喷嘴就执行挤出命令。
  • 起始 G-code、换料宏、暂停恢复宏中缺少等待温度命令。
  • 目标温度尚未达到，宏提前执行了挤出或回抽。
  • 温度传感器读数异常，导致 Klipper 判断喷嘴未达到可挤出温度。

解决方法：

  1. 执行挤出前确认喷嘴已达到耗材所需温度。
  2. 检查起始 G-code、M600、PAUSE、RESUME 等宏中是否有等待温度逻辑。
  3. 在需要等待温度的位置使用 M109 或 Klipper 等效等待命令。
  4. 检查热敏电阻和温度曲线，确认温度读数稳定。
  5. 不建议为了绕过报错长期降低 min_extrude_temp。

性能与超时问题​

归位超时问题​

归位时出现通信超时、MCU 掉线或多 MCU 归位异常，可参考 归位超时问题。

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

报错信息：步进事件已经超出 MCU 可处理的时间范围，打印机会进入 shutdown 状态。

Loading...

参考场景：此报错不一定由网床配置引起，实际原因需要结合 klippy.log 和当前操作判断。执行多点扫床时，如果 [bed_mesh] 中的 probe_count 设置过大，例如 20,20，并且同时配置了较高的 mesh_pps，例如 mesh_pps: 4,4，可能会生成过密的网格数据，增加上位机计算和运动规划压力，从而触发类似报错。

解决方法：

  1. 如果报错出现在多点扫床过程中，可先降低 [bed_mesh] 中的 probe_count，例如改为 7,7 或 9,9 测试。
  2. 如果配置了较高的 mesh_pps，可降低或删除该配置，例如改为 mesh_pps: 2,2；如果不需要插值，可按实际需求设为 0,0。
  3. 保存配置并重启 Klipper 后，重新执行触发报错前的操作。
  4. 如果仍然报错，继续检查上位机负载、打印速度、加速度、通信质量和当前正在执行的宏或 G-code。

MCU 'mcu' shutdown: Timer too close​

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

Loading...

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

解决方法：

  1. 降低步进电机细分，减少 MCU 脉冲处理压力。
  2. 降低打印速度和加速度，观察问题是否消失。
  3. 检查上位机负载、供电和 USB / CAN 通信质量。
  4. 检查 MCU 与上位机之间的通信线是否靠近电机线、加热线、热床线或电源线，必要时重新走线或更换带屏蔽的通信线。
  5. 检查机器接地情况，未可靠接地的机器可能更容易出现通信干扰。
  6. 如果问题发生在归位阶段，请参考 归位超时问题。
  7. 如果问题持续存在，再考虑重新刷写上位机系统或固件。

树莓派用户可检查 NTP 时间同步状态：

sudo timedatectl status | grep "NTP service"

如需临时关闭 NTP 同步，可执行：

sudo timedatectl set-ntp false

确认问题与 NTP 无关后，可按实际需要重新开启：

sudo timedatectl set-ntp true
Loading...