Skip to main content

Motion, Endstop, and Leveling Error

This page organizes errors related to movement range, homing, endstops, probes, bed mesh, and multi-Z leveling. When dealing with wiring, connectors, or manual mechanical adjustments, please disconnect power first.

Move out of range​

Error Message: The target coordinate exceeds the movement range allowed by Klipper. The log usually shows something like Move out of range: X Y Z [E].

Loading...

Common Causes:

  • The machine dimensions in the slicer do not match position_min / position_max in the Klipper configuration.
  • Start G-code, end G-code, filament change macro, or pause macro moves outside the machine's range.
  • After using skew correction, probe offset, or bed mesh configuration, the calculated coordinates become negative or exceed the maximum travel.
  • The model height exceeds the Z-axis maximum travel.

Solutions:

  1. Determine which axis is out of range based on the coordinates in the error.
  2. Check the position_min, position_max for the corresponding axis and the machine dimensions in the slicer.
  3. Check the parking coordinates in macros for start, end, pause, and filament change, avoiding positions like 0,0 or the maximum boundaries.
  4. If the error occurs during bed mesh scanning, check mesh_min, mesh_max in [bed_mesh] and the probe offset.
  5. Save the configuration, restart Klipper, and retest.

Related Configuration References: Macros, Homing and Direction Calibration Guide.

Must home axis first​

Error Message: The axis has not been homed yet, so the current move command cannot be executed.

Common Causes:

  • G28 was not executed after power-on or FIRMWARE_RESTART.
  • A macro executes a move command before a homing command.
  • The machine state is reset after print pause, resume, or cancel.
  • Abnormal configuration of homing macros, probe macros, or sensorless homing prevents Klipper from correctly recording the homed state.

Solutions:

  1. Manually execute G28 before moving the corresponding axis.
  2. Check the start G-code and macros to ensure homing is completed before any move commands.
  3. If Klipper or firmware was recently updated, check if the homing-related macros are still compatible with the current version.
  4. If using sensorless homing, check driver current, sensitivity, and homing_retract_dist.

Related Configuration References: Homing and Direction Calibration Guide, Sensorless Homing Usage.

Endstop still triggered after retract​

Error Message: After triggering the endstop during homing and retracting by homing_retract_dist, the endstop is still triggered.

Common Causes:

  • The normally open/normally closed logic of the endstop switch is configured incorrectly.
  • The endstop switch is stuck, damaged, or wired incorrectly.
  • homing_retract_dist is too small, so the switch is still pressed after retraction.
  • Sensorless homing sensitivity is too high, still considered triggered after retraction.
  • Incorrect enable_pin, motor direction, or endstop pin configuration, causing abnormal homing behavior.

Solutions:

Power Off

Before checking the endstop connector, motor wiring, or re-plugging cables, completely turn off the printer and disconnect the power supply. When testing with power on, only use web commands and manually trigger the endstop mechanically; do not touch the terminals.

  1. Run QUERY_ENDSTOPS to confirm the state is open when not triggered and TRIGGERED when manually triggered.
  2. If the state is reversed, add or remove ! before the endstop pin.
  3. Power off and check the mechanical state, wiring, and connector of the endstop switch.
  4. Slightly increase homing_retract_dist and retest.
  5. If using sensorless homing, reduce sensitivity and ensure the homing current is appropriate.

Related Configuration References: Endstop Related, Sensorless Homing Usage.

No trigger on endstop after full movement​

Error Message: No trigger on x after full movement, No trigger on y after full movement, or similar endstop not triggered messages.

Common Causes:

  • Incorrect homing direction configuration, causing the motor to move away from the endstop.
  • The endstop switch is not connected, the connector is loose, or the pin configuration is wrong.
  • position_endstop, position_min, position_max do not match the actual travel, so the homing distance is insufficient.
  • Sensorless homing sensitivity is too low, not registering a trigger when hitting the mechanical limit.
  • Incorrect motor wiring or direction configuration, causing the axis to move in the opposite direction.

Solutions:

  1. Run QUERY_ENDSTOPS and manually press the endstop to confirm the state changes from open to TRIGGERED.
  2. Move the axis a small distance to confirm its direction, then check if ! before dir_pin needs adjustment.
  3. Ensure homing_positive_dir matches the direction where the endstop is located.
  4. Check if position_endstop, position_min, position_max correspond to the actual mechanical travel.
  5. In sensorless homing scenarios, reduce the homing speed and adjust TMC sensitivity.

Related Configuration References: Homing and Direction Calibration Guide, Endstop Related.

Probe and Leveling Issues​

Power Off

Before checking the wiring, connectors, or pinout of probes like BLTouch, Probe, TAP, Klicky, EDDY, etc., completely turn off the printer and disconnect the power supply. When powered on, only execute query commands or observe status; do not plug or unplug cables.

Probe triggered prior to movement​

Error Message: The probe is already in a triggered state before the homing or probing movement begins.

Causes:

  • The probe defaults to TRIGGERED state after power-on or reset.
  • Incorrect probe wiring or poor contact, keeping the signal constantly triggered.
  • Mechanical probe failure, e.g., BLTouch pin stuck and cannot retract.
  • Z-axis is already at its lowest position, pressing the probe.

Solutions:

  1. Run QUERY_PROBE to confirm the state is open when not touching the bed.
  2. Run QUERY_ENDSTOPS to confirm the endstop/probe signal is correct.
  3. For BLTouch: BLTOUCH_DEBUG COMMAND=pin_up to ensure the pin retracts, then QUERY_PROBE to confirm.
  4. Check the Z-axis current position; lift the Z-axis if necessary.
  5. Power off and check the probe wiring and sensor_pin configuration.

Related Configuration References: Endstop Related, Common Debugging Commands.

No trigger on probe after full movement​

Error Message: The probe did not trigger during its full travel downward.

Common Causes:

  • Incorrect probe wiring, power supply, or pin configuration.
  • Incorrect probe mounting height, preventing it from triggering within its travel.
  • Incorrect Z-axis direction, probe offset, or leveling area configuration.
  • Faulty probe hardware, or poor contact in the cable during movement.

Solutions:

  1. Run QUERY_PROBE and manually trigger the probe to confirm the state changes correctly.
  2. Power off and check the probe's power supply, signal wire, and configured pins.
  3. Check the probe mounting height to ensure it is within the triggerable range before probing down.
  4. Check if the probe points in [probe], [bed_mesh], [z_tilt], or [quad_gantry_level] are outside the bed.
  5. If the problem occurs only at specific positions, focus on cable drag and probe offset.

Related Configuration References: Endstop Related, Macros.

Probe samples exceed samples_tolerance​

Error Message: Probe samples exceed samples_tolerance, or the log repeatedly shows Probe samples exceed tolerance. Retrying....

Common Causes:

  • Poor probe repeatability; the Z-height difference between samples exceeds samples_tolerance.
  • The bed, gantry, hotend, or probe is not securely fixed, causing wobble during probing.
  • The probe speed is too fast, or the probe travel/retract distance is unsuitable.
  • Inductive, eddy current, or pressure sensors are affected by temperature drift or electromagnetic interference.

Solutions:

  1. Check if the probe, hotend, bed, and gantry structure are securely fastened.
  2. Reduce speed in [probe] and increase sample_retract_dist appropriately.
  3. Temporarily relax samples_tolerance for testing, e.g., change from 0.01 to 0.03 or 0.05.
  4. If using an inductive/eddy current probe, wait for the bed and nozzle temperatures to stabilize before leveling.
  5. If the problem occurs only in a specific area, check the bed surface, magnetic sheet, cable drag, and probe offset in that area.

Related Configuration References: Machine Calibration, Macros.

Must home before probe​

Error Message: Must home before probe.

Common Causes:

  • Running PROBE, BED_MESH_CALIBRATE, Z_TILT_ADJUST, or QUAD_GANTRY_LEVEL without executing G28 first.
  • A macro calls a leveling command without ensuring XY/Z are homed.
  • After FIRMWARE_RESTART, emergency stop, or error recovery, Klipper has cleared the homing state.

Solutions:

  1. Execute G28 first, then run the probe or leveling command.
  2. Add a homing check or directly include G28 at the beginning of leveling macros.
  3. If using an independent Z probe, ensure endstop_pin: probe:z_virtual_endstop and [probe] configurations are complete.

Related Configuration References: Homing and Direction Calibration Guide, Macros.

BLTouch failed to verify sensor state​

Error Message: BLTouch failed to verify sensor state; retrying. repeatedly, leading to an error.

Common Causes:

  • Cloned/counterfeit BLTouch cannot pass Klipper's internal sensor verification.
  • sensor_pin is configured without a pull-up resistor (missing ^ prefix).
  • Incorrect wiring for the BLTouch control pin or sensor pin.
  • Probe self-test failed, indicated by a flashing red light.

Solutions:

  1. First, run BLTOUCH_DEBUG COMMAND=pin_down, BLTOUCH_DEBUG COMMAND=touch_mode, and QUERY_PROBE to confirm the state.

  2. If manual tests pass but automatic homing/probing still errors, add the following to [bltouch]:

    pin_up_touch_mode_reports_triggered: False

  3. Ensure sensor_pin has a pull-up resistor, e.g., sensor_pin: ^PC4.

  4. Check if the BLTouch self-test is normal: The probe should extend and retract a few times on power-up, then the red LED should be solid on.

BLTouch failed to raise probe​

Error Message: After homing or probing, Klipper detects that the BLTouch probe did not retract successfully.

Common Causes:

  • Older cloned BLTouch versions cannot report the probe retracted state.
  • The probe is mechanically stuck, the magnet core has shifted, or a screw is loose.
  • Incorrect control_pin wiring or configuration.

Solutions:

  1. Test the probe control functions: BLTOUCH_DEBUG COMMAND=pin_down and BLTOUCH_DEBUG COMMAND=pin_up.

  2. If the physical action is correct but the error persists, add the following to [bltouch]:

    pin_up_reports_not_triggered: False

  3. If the probe is stuck, it is recommended to replace the probe module or contact after-sales support. Do not disassemble powered equipment.

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

Error Message: horizontal_move_z can't be less than probe's z_offset.

Common Causes:

  • The z_offset saved after PROBE_CALIBRATE is larger than the horizontal_move_z in the leveling configuration.
  • The probe mounting height changed significantly after replacing the nozzle, probe mount, or hotend.
  • horizontal_move_z or z_offset is configured multiple times in different include files.

Solutions:

  1. Search all occurrences of horizontal_move_z and z_offset to confirm the final effective configuration.
  2. Set horizontal_move_z in the relevant leveling configurations to a safe value larger than the probe z_offset.
  3. If z_offset is abnormally large, re-check the probe mounting height and run PROBE_CALIBRATE.
  4. After saving, run RESTART, then retest BED_MESH_CALIBRATE or the leveling command.

Related Configuration References: Machine Calibration, Macros.

bed_mesh: cannot exceed a probe_count of 6​

Error Message: bed_mesh: cannot exceed a probe_count of 6 when using lagrange interpolation.

Cause: lagrange interpolation can oscillate with a high number of samples. Klipper limits the probe count per axis to 6 or less when using this algorithm.

Solutions:

  1. If a denser grid like 7x7 or 9x9 is needed, set the following in [bed_mesh]:

    algorithm: bicubic

  2. If a dense grid is unnecessary, reduce probe_count to 6,6 or lower.

  3. When using adaptive bed mesh with PROBE_COUNT passed from the slicer or macro, ensure the final count and algorithm are compatible.

  4. Save the configuration and run RESTART.

Related Configuration References: Macros.

bed_mesh: Unknown profile​

Error Message: bed_mesh: Unknown profile [xxx] or a failure to load a bed mesh profile.

Common Causes:

  • The start G-code or macro executes BED_MESH_PROFILE LOAD=xxx, but this profile name has never been saved.
  • BED_MESH_CLEAR was executed, or the bed mesh data in the auto-save section was deleted.
  • SAVE_CONFIG was not executed after completing the bed mesh calibration.
  • The profile name has case or whitespace mismatches.

Solutions:

  1. Run BED_MESH_OUTPUT or check the auto-save section at the end of the configuration to see existing profile names.
  2. If the required profile does not exist, re-run BED_MESH_CALIBRATE, then run SAVE_CONFIG.
  3. Modify BED_MESH_PROFILE LOAD= in the start G-code to match the actual saved profile name.
  4. If a new mesh is always generated before each print, remove unnecessary profile load commands.

Related Configuration References: Macros.

Z_TILT_ADJUST / QUAD_GANTRY_LEVEL Errors​

Error Messages: Z_TILT_ADJUST: Point X,Y not reachable with current probe offset, QUAD_GANTRY_LEVEL: Max adjustment X.XXXX exceeds limit, or excessive deviation remains after gantry leveling.

Common Causes:

  • Incorrect probe offset configuration, causing the calculated probing point to be outside the bed.
  • The gantry deviation across multiple Z-axes exceeds the max_adjust limit.
  • Z motor directions are inconsistent, causing the gantry to tilt in the opposite direction.
  • Inconsistent endstop switch mounting heights, leading to large differences in Z-axis starting positions after homing.
  • Loose mechanical structure of the gantry, belt slipping, or excessive lead screw nut backlash.

Solutions:

Power Off

Before manually adjusting Z lead screws, timing belts, couplers, or checking gantry endstop mounting, completely turn off the printer and disconnect the power supply. Do not forcefully rotate lead screws or timing belts while the motors are holding torque.

  1. Check x_offset, y_offset in [probe], and the points in [z_tilt] or [quad_gantry_level].
  2. If the deviation exceeds max_adjust, completely power off, manually level the gantry roughly, then power on, home, and run leveling again.
  3. Execute STEPPER_BUZZ STEPPER=stepper_z and STEPPER_BUZZ STEPPER=stepper_z1 (adjust names as needed) to confirm each Z motor moves in the same direction individually.
  4. Power off and check if the endstop switch mounting heights at each gantry corner are consistent, and if lead screw nuts, timing belts, and couplers are tight or slipping.
  5. If the max_adjust limit is simply too small, it can be increased moderately, but not by more than 2-3 times the default value.

Related Configuration References: Homing and Direction Calibration Guide.

Loading...