跳到主要内容

运动、限位与调平报错

本页整理移动范围、归位、限位、探针、网床和多 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 后重新测试。

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

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 灵敏度。

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

探针与调平问题​

断电操作

检查 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 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. 如果探针卡住，建议更换探针模块或联系售后，不要拆解带电设备。

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 加载命令。

相关配置参考：宏介绍。

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 倍默认值。

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

Loading...