跳到主要内容

运动、限位与调平报错

本页整理移动范围、归位、限位、探针、网床和多 Z 调平相关报错。涉及接线、插头、手动机械调整时，请先断电再操作。

Move out of range​

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

Loading...

常见原因：

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

解决方法：

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

相关配置参考：宏介绍、归位与方向校准指南。

Unable to parse move / Invalid speed​

报错信息：Unable to parse move 'G1 Z'、Unable to parse move 'G1 X... Y... Z...'、Invalid speed in 'G1 ...'、Machine does not support G20 (inches) command、Unknown g-code state: xxx。

常见原因：

  • G-code 行格式不完整，例如 G1 Z 后面缺少具体坐标值。
  • 宏变量为空，最终拼出的移动命令缺少 X、Y、Z、E 或 F 数值。
  • 切片器起始/结束 G-code 中换行、花括号、变量名或转义格式错误。
  • F 速度参数为空、为 0 或不是数字。
  • G-code 文件使用了英寸模式 G20，Klipper 不支持该命令。
  • 宏中 SAVE_GCODE_STATE / RESTORE_GCODE_STATE 使用的名称不一致。

解决方法：

  1. 在 klippy.log 中找到完整的报错行，确认是哪一条 G1、G0 或状态命令出错。
  2. 检查切片器起始、结束、暂停、恢复和换料宏，确认所有移动命令都有完整数值。
  3. 对宏参数设置默认值，并在使用前转换为数字，例如 params.Z|default(10)|float。
  4. 确认切片器单位为毫米，不要输出 G20。
  5. 如果报 Unknown g-code state，检查 SAVE_GCODE_STATE NAME= 和 RESTORE_GCODE_STATE NAME= 是否使用同一个名称。

相关配置参考：宏介绍。

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 endstop after full movement​

报错信息：No trigger on x after full movement、No trigger on y after full movement 或类似限位未触发提示。

常见原因：

  • 归位方向配置错误，电机向远离限位的方向移动。
  • 限位开关未接通、插头松动或引脚配置错误。
  • position_endstop、position_min、position_max 配置与实际行程不匹配，归位距离不够。
  • 无限位归位灵敏度过低，撞到机械端点后仍未被判断为触发。
  • 电机线序或方向配置错误，导致轴移动方向与预期相反。

解决方法：

  1. 执行 QUERY_ENDSTOPS，手动按下限位，确认状态能从 open 变为 TRIGGERED。
  2. 用小距离移动确认轴方向，再检查 dir_pin 前的 ! 是否需要调整。
  3. 确认 homing_positive_dir 与限位所在方向一致。
  4. 检查 position_endstop、position_min、position_max 是否符合实际机械行程。
  5. 无限位归位场景下，降低归位速度并调整 TMC 灵敏度。

相关配置参考：归位与方向校准指南、限位相关。

无限位归位（Sensorless Homing）排查​

无限位归位通过 TMC 驱动的 DIAG 信号判断电机堵转，替代物理限位开关。配置或灵敏度不当时会出现以下报错。完整的兼容性检查、参考配置与灵敏度调试方法见 无限位使用。

归位未触发：No trigger on x after full movement​

报错信息：使用 virtual_endstop 归位时提示 No trigger on x after full movement 或 No trigger on y after full movement，滑车撞到端点仍不停止。

常见原因：

  • 灵敏度阈值不合适：TMC2209 的 driver_SGTHRS 过低（不够敏感），或 TMC5160 / TMC2240 / TMC2130 的 driver_SGT 过高。
  • B 类主板未安装 DIAG 跳线帽，或对应限位口仍接了其他设备。
  • diag_pin 缺少上拉符号 ^，开漏信号无法稳定触发。
  • 归位速度过低、驱动电流过低，堵转电流变化不足以触发 DIAG 信号。
断电操作

检查跳线帽、限位口接线或插拔线束前，请先关闭打印机并断开电源，不要在通电状态下触碰端子或插拔线束。

解决方法：

  1. 按 无限位使用 · 测试灵敏度 的方法，从最高灵敏度开始逐步调试 SGTHRS / sgt。
  2. 确认 diag_pin 带 ^ 上拉（如 diag_pin: ^PD9）；TMC5160 等双 DIAG 引脚驱动需确认选用的是 diag0_pin 还是 diag1_pin。
  3. B 类主板确认已安装 DIAG 跳线帽，且对应限位口没有接其他设备。
  4. 适当提高归位电流与归位速度后复测。

配置报错：Unknown pin chip name​

报错信息：启动时报 Unknown pin chip name 'tmc5160 stepper_x'、Unknown pin chip name '^awd' 等，Klipper 无法进入 ready 状态。

常见原因：

  • endstop_pin 中驱动名与轴名之间误用了空格，例如写成 tmc5160 stepper_x:virtual_endstop；正确写法必须用下划线 tmc5160_stepper_x:virtual_endstop。
  • diag_pin / diag0_pin / diag1_pin 引脚名拼写错误或带入了非法字符。

解决方法：

  1. 检查 [stepper_x] 的 endstop_pin，确认格式为 tmcXXXX_stepper_x:virtual_endstop，驱动名与轴名之间是下划线而非空格。
  2. 驱动配置段名 [tmcXXXX stepper_x] 内部用空格，而 endstop_pin 引用时必须改用下划线，两者名称要能对应。
  3. 核对 diag_pin 引脚名拼写，仅允许 ^、! 前缀加合法引脚名。

配置报错：Could not find any TMC driver config section​

报错信息：Could not find any TMC driver config section for 'stepper_x' required by TMC autotuning。

常见原因：

  • endstop_pin 引用了 tmcXXXX_stepper_x:virtual_endstop，但配置中没有对应的 [tmcXXXX stepper_x] 驱动段，或驱动段名与引用不一致。
  • 驱动段被注释、拼写错误或轴名不匹配。

解决方法：

  1. 确认存在与 endstop_pin 引用完全对应的驱动配置段，例如 endstop_pin: tmc2209_stepper_x:virtual_endstop 必须有 [tmc2209 stepper_x]。
  2. 检查驱动段是否被注释或轴名写错（stepper_x 与 stepper_y 不要混淆）。

归位时急停：Homing failed due to printer shutdown​

报错信息：归位过程中打印机进入 shutdown，提示 Homing failed due to printer shutdown。

常见原因：

  • 这不是无限位专属故障，而是归位期间发生了其他 shutdown（如 DIAG 信号抖动误触发、驱动报错、服务重启）引发了急停。
  • 真实原因需要看 klippy.log 中 Homing failed 之前的第一条 shutdown 报错。

解决方法：

  1. 打开 klippy.log，搜索 Homing failed due to printer shutdown 上方的第一条 shutdown 报错，按对应分类排查。
  2. 如果上方是 Can't reset time when stepper active，按 系统、性能与服务报错 处理。
  3. 如果是 DIAG 信号抖动导致误触发，检查 diag_pin 上拉与跳线帽，并适当降低灵敏度。

相关文档：无限位使用、No trigger on endstop after full movement、TMC 报错排查

探针与调平问题​

断电操作

检查 BLTouch、Probe、TAP、Klicky、EDDY 等探针接线、插头或线序前，请完全关闭打印机并断开电源供应。通电时仅执行查询命令或观察状态，不要插拔线束。

Probe triggered prior to movement​

报错信息：在归位或探测移动开始之前，探针已经处于触发状态。

报错原因：

  • 探针在上电或复位后默认状态为 TRIGGERED。
  • 探针线序错误或接触不良，导致信号始终处于触发状态。
  • 探针机械故障，如 BLTouch 探针卡住无法缩回。
  • Z 轴已处于最低位置导致探针被压住。

解决方法：

  1. 执行 QUERY_PROBE 在未接触热床时确认状态应为 open。
  2. 执行 QUERY_ENDSTOPS 确认限位/探针信号是否正确。
  3. 对于 BLTouch：BLTOUCH_DEBUG COMMAND=pin_up 确保探针缩回，再 QUERY_PROBE 确认。
  4. 检查 Z 轴当前位置，必要时先抬升 Z 轴。
  5. 断电后检查探针接线和 sensor_pin 配置。

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

No trigger on probe after full movement​

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

常见原因：

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

解决方法：

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

相关配置参考：限位相关、宏介绍。

Probe samples exceed samples_tolerance​

报错信息：Probe samples exceed samples_tolerance，或日志中反复出现 Probe samples exceed tolerance. Retrying...。

常见原因：

  • 探针重复性差，几次采样的 Z 高度差超过 samples_tolerance。
  • 热床、龙门、喷头或探针固定不牢，探测时有晃动。
  • 探针速度过快，或者下探距离/回弹距离不合适。
  • 电感、涡流或压力传感器受温度漂移、电磁干扰影响。

解决方法：

  1. 检查探针、热端、床板和龙门结构是否固定牢靠。
  2. 降低 [probe] 中的 speed，适当增大 sample_retract_dist。
  3. 先临时放宽 samples_tolerance 测试，例如从 0.01 调到 0.03 或 0.05。
  4. 如果使用电感/涡流探针，等待热床和喷嘴温度稳定后再调平。
  5. 问题只在某一区域出现时，检查该区域床面、磁贴、线束拖动和探针偏移。

相关配置参考：机器校准、宏介绍。

Must home before probe​

报错信息：Must home before probe。

常见原因：

  • 还没有执行 G28 就运行 PROBE、BED_MESH_CALIBRATE、Z_TILT_ADJUST 或 QUAD_GANTRY_LEVEL。
  • 宏中调用调平命令前没有保证 XY/Z 已归位。
  • FIRMWARE_RESTART、急停或报错恢复后，Klipper 已清除归位状态。

解决方法：

  1. 先执行 G28，再执行探针或调平命令。
  2. 在调平宏开头加入归位判断或直接加入 G28。
  3. 如果使用独立 Z 探针，确认 endstop_pin: probe:z_virtual_endstop 和 [probe] 配置完整。

相关配置参考：归位与方向校准指南、宏介绍。

BLTouch failed to verify sensor state​

报错信息：BLTouch failed to verify sensor state; retrying. 多次重试后报错。

常见原因：

  • 盗版/克隆 BLTouch 无法通过 Klipper 内部传感器验证。
  • sensor_pin 未配置上拉电阻（缺少 ^ 前缀）。
  • BLTouch 控制引脚或传感器引脚接线错误。
  • 探针自检失败，红灯闪烁。

解决方法：

  1. 先运行 BLTOUCH_DEBUG COMMAND=pin_down、BLTOUCH_DEBUG COMMAND=touch_mode 和 QUERY_PROBE 确认状态。

  2. 如果手动测试通过但自动归位/探测仍报错，在 [bltouch] 中添加：

    pin_up_touch_mode_reports_triggered: False

  3. 确保 sensor_pin 配置了上拉电阻，如 sensor_pin: ^PC4。

  4. 检查 BLTouch 自检是否正常：通电后探针伸缩几次，红灯常亮即为正常。

BLTouch failed to deploy​

报错信息：BLTouch failed to deploy。

常见原因：

  • BLTouch 探针机械卡住，无法伸出。
  • control_pin 接线或配置错误，探针未收到伸出信号。
  • 盗版/克隆 BLTouch 时序不兼容。
  • 探针供电不足（使用了主板 3.3V 而非 5V）。

解决方法：

  1. 手动测试探针控制：BLTOUCH_DEBUG COMMAND=pin_down，观察探针是否伸出。
  2. 确认 [bltouch] 中 control_pin 和 sensor_pin 与主板文档一致。
  3. 检查 BLTouch 供电是否为 5V（部分主板需跳线选择）。
  4. 如果探针完全无动作，断电后检查接线和插头，必要时更换探针模块。

BLTouch failed to raise probe​

报错信息：归位或探测后 Klipper 检测到 BLTouch 探针未成功缩回。

常见原因：

  • 老版本克隆 BLTouch 无法报告探针缩回状态。
  • 探针机械卡住，磁芯移位或螺丝松动。
  • control_pin 接线或配置错误。

解决方法：

  1. 测试探针控制功能：BLTOUCH_DEBUG COMMAND=pin_down 和 BLTOUCH_DEBUG COMMAND=pin_up。

  2. 如果动作正常但报错，在 [bltouch] 中添加：

    pin_up_reports_not_triggered: False

  3. 如果探针卡住，建议更换探针模块或联系售后，不要拆解带电设备。

完整指南：BLTouch 接线、测试、克隆兼容性和输出模式等完整配置说明见 BLTouch 配置与排查。

Communication timeout during homing​

报错信息：Communication timeout during homing x、Communication timeout during homing y 等。

常见原因：

  • 归位过程中 CAN 总线受到电机运动产生的电磁干扰，通信丢包。
  • USB 通信线接触不良，运动报动时断开。
  • MCU 过载（如归位同时触发大量传感器查询）。

解决方法：

  1. 检查 CAN / USB 通信线走线，确保远离电机线、加热线和电源线。
  2. 确认通信线插头牢固，更换质量更好的屏蔽线。
  3. 确认所有 MCU 固件版本一致。
  4. 如果只在特定轴归位时出现，重点检查该轴电机线和限位开关线束的屏蔽与接地。

相关排查：Lost communication with MCU、CAN 报错排查

horizontal_move_z can't be less than probe's z_offset​

报错信息：horizontal_move_z can't be less than probe's z_offset。

常见原因：

  • PROBE_CALIBRATE 后保存的 z_offset 大于调平配置中的 horizontal_move_z。
  • 更换喷嘴、探针支架或热端后，探针安装高度变化很大。
  • 多个 include 文件中重复配置了 horizontal_move_z 或 z_offset。

解决方法：

  1. 搜索所有 horizontal_move_z 和 z_offset，确认最终生效配置。
  2. 将相关调平配置中的 horizontal_move_z 设置为大于探针 z_offset 的安全值。
  3. 如果 z_offset 异常偏大，重新检查探针安装高度并执行 PROBE_CALIBRATE。
  4. 保存后执行 RESTART，再重新测试 BED_MESH_CALIBRATE 或调平命令。

相关配置参考：机器校准、宏介绍。

bed_mesh: cannot exceed a probe_count of 6​

报错信息：bed_mesh: cannot exceed a probe_count of 6 when using lagrange interpolation。

报错原因：lagrange 插值在高采样数量下容易振荡，Klipper 限制使用该算法时单轴探测点数量不能超过 6。

解决方法：

  1. 如果需要 7x7、9x9 或更密的网格，在 [bed_mesh] 中设置：

    algorithm: bicubic

  2. 如果不需要密集网格，将 probe_count 降到 6,6 或以下。

  3. 自适应网床由切片机或宏传入 PROBE_COUNT 时，也要确认最终点数和算法匹配。

  4. 修改后保存并执行 RESTART。

相关配置参考：宏介绍。

bed_mesh: Unknown profile​

报错信息：bed_mesh: Unknown profile [xxx] 或加载网床配置时提示找不到 profile。

常见原因：

  • 起始 G-code 或宏中执行了 BED_MESH_PROFILE LOAD=xxx，但该名称从未保存。
  • 执行过 BED_MESH_CLEAR 或删除了自动保存区中的网床数据。
  • 网床校准完成后没有执行 SAVE_CONFIG。
  • profile 名称大小写或空格不一致。

解决方法：

  1. 执行 BED_MESH_OUTPUT 或查看配置末尾自动保存区，确认已有 profile 名称。
  2. 如果没有需要的 profile，重新执行 BED_MESH_CALIBRATE，再执行 SAVE_CONFIG。
  3. 修改起始 G-code 中的 BED_MESH_PROFILE LOAD=，使名称与实际保存名称一致。
  4. 如果每次打印前都重新扫床，可删除不必要的 profile 加载命令。

相关配置参考：宏介绍。

bed_mesh 高级配置报错​

报错信息：bed_mesh: ERROR, fade_target lies outside of mesh z range、bed_mesh: Mesh extends outside of the fade range、bed_mesh: Cannot probe zero reference position、bed_mesh: invalid min/max points、bed_mesh: malformed 'xxx' value。

常见原因：

  • fade_target 超出了当前网床 Z 高度范围，或网床数据整体偏差过大。
  • mesh_min、mesh_max、zero_reference_position 与探针偏移计算后落在不可探测区域。
  • faulty_region 覆盖了零参考点，导致 Klipper 无法探测参考位置。
  • 坐标列表格式错误，缺少逗号或使用了中文标点。
  • 自适应网床宏传入的 MESH_MIN / MESH_MAX 与机器尺寸、探针偏移不匹配。

解决方法：

  1. 检查 [bed_mesh] 中 mesh_min、mesh_max、probe_count、fade_start、fade_end、fade_target。
  2. 如果不清楚 fade_target 的意义，优先删除该项，让 Klipper 使用默认行为。
  3. 确认所有探测点加上 [probe] 的 x_offset / y_offset 后仍在机器可移动范围内。
  4. 如果配置了 zero_reference_position 或 faulty_region，确认零参考点没有落在故障区域内。
  5. 自适应网床报错时，先用固定 mesh_min / mesh_max 测试，确认基础网床配置正常后再恢复宏。

相关配置参考：宏介绍、机器校准。

Z_TILT_ADJUST / QUAD_GANTRY_LEVEL 报错​

报错信息：Z_TILT_ADJUST: Point X,Y not reachable with current probe offset、QUAD_GANTRY_LEVEL: Max adjustment X.XXXX exceeds limit 或龙门调平后偏差仍然过大。

常见原因：

  • 探针偏移配置不正确，导致计算的探测点超出热床范围。
  • 多个 Z 轴的龙门偏差超出了 max_adjust 允许范围。
  • Z 轴电机方向不一致，导致龙门向相反方向倾斜。
  • 限位开关安装高度不一致，归位后各 Z 轴起始位置差异过大。
  • 龙门机械结构松动、皮带打滑或丝杆螺母间隙过大。

解决方法：

断电操作

手动调整 Z 丝杆、同步带、联轴器，或检查龙门限位安装前，请完全关闭打印机并断开电源供应。不要在电机上电保持力矩时强行旋转丝杆或同步带。

  1. 检查 [probe] 中的 x_offset、y_offset，以及 [z_tilt] 或 [quad_gantry_level] 中的 points。
  2. 如果偏差超出 max_adjust，完全断电后手动调整龙门大致水平，再重新上电归位和执行调平。
  3. 执行 STEPPER_BUZZ STEPPER=stepper_z 和 STEPPER_BUZZ STEPPER=stepper_z1（按实际名称），确认每个 Z 电机单独运动方向一致。
  4. 断电后检查龙门各角限位开关安装高度是否一致，丝杆螺母、同步带松紧和联轴器是否有打滑。
  5. 如果只是 max_adjust 限制太小，可适当增大该值，但不要超过 2-3 倍默认值。

相关配置参考：归位与方向校准指南。

no samples between time​

报错信息：no samples between time X.X and X.X，通常在执行 BED_MESH_CALIBRATE 后出现。

常见原因：

  • EDDY 涡流探针或 Cartographer 等流式采样探针的固件版本与上位机 Klipper 不匹配。
  • 探针数据流在网床采样期间中断（CAN 通信抖动、USB 带宽不足）。
  • 升级 Klipper 后未同步更新探针模块固件。
  • 上位机 CPU 负载过高，导致采样数据时间戳异常。

解决方法：

  1. 确认探针模块（EDDY、Cartographer 等）固件版本与当前 Klipper 版本匹配，必要时重新刷写探针固件。
  2. 检查 CAN 总线状态，确认 bytes_retransmit、bytes_invalid 没有持续增长。
  3. 临时关闭摄像头、KlipperScreen 和其他高负载服务后重新执行网床校准。
  4. 如果只在特定区域报错，检查该区域是否超出探针有效感应范围。
  5. 尝试降低网床采样速度（减小 speed 参数）后复测。

EDDY 探针相关：EDDY 问题合集

SVD did not converge in Linear Least Squares​

报错信息：numpy.linalg.LinAlgError: SVD did not converge in Linear Least Squares，通常在执行 BED_MESH_CALIBRATE 或 ACCEPT 后触发 shutdown。

常见原因：

  • 网床采样点数据异常（全部相同、包含 NaN 或极端跳变），numpy 无法完成矩阵拟合。
  • 探针在采样期间触发异常（如 EDDY 数据流中断、Cartographer 超出模型范围）。
  • 热床表面存在金属异物或探针感应面污染，导致个别点读数严重偏离。
  • 上位机 numpy 版本过旧或安装损坏。

解决方法：

  1. 重新执行 BED_MESH_CALIBRATE，观察是否每次都在同一点失败。
  2. 检查热床表面是否清洁，探针感应面是否有残留耗材或金属碎片。
  3. 如果探针为 EDDY / Cartographer，确认固件版本与 Klipper 匹配，并检查 CAN 通信稳定性。
  4. 尝试减小 probe_count（如从 7x7 降为 5x5）后复测，排除单点异常影响。
  5. 如果问题持续，尝试更新上位机 numpy：pip install --upgrade numpy。
  6. 检查 klippy.log 中报错前是否有 Toolhead stopped outside model range 或探针超时等前置错误。
Loading...