Skip to main content

Motion, Endstop, and Leveling Errors

This page summarizes errors related to movement range, homing, endstops, probes, bed mesh, and multi-Z leveling. When dealing with wiring, connectors, or manual mechanical adjustments, please power off the device before operating.

Move out of range​

Error Message: The target coordinate exceeds the movement range allowed by Klipper. The log typically 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 macros, or pause macros move outside the machine's physical range.
  • After configuring skew correction, probe offsets, or bed mesh, the calculated coordinates become negative or exceed the maximum travel.
  • The model height exceeds the Z-axis maximum travel.

Solutions:

  1. Identify 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 start, end, pause, and filament change macros. Avoid parking at 0,0 or the maximum boundaries.
  4. If the error occurs during bed probing, check mesh_min, mesh_max, and the probe offset in the [bed_mesh] section.
  5. Save the configuration and restart Klipper before testing again.

Related configuration reference: Macros, Homing and Direction Calibration Guide.

Unable to parse move / Invalid speed​

Error Message: 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.

Common Causes:

  • The G-code line format is incomplete, e.g., G1 Z is missing the specific coordinate value.
  • A macro variable is empty, resulting in a move command lacking X, Y, Z, E, or F values.
  • Incorrect line breaks, curly braces, variable names, or escape formatting in the slicer's start/end G-code.
  • The F speed parameter is empty, zero, or not a number.
  • The G-code file uses inch mode G20, which Klipper does not support.
  • The name used in SAVE_GCODE_STATE / RESTORE_GCODE_STATE macros is inconsistent.

Solutions:

  1. Find the complete error line in klippy.log to identify which G1, G0, or state command is failing.
  2. Check the slicer's start, end, pause, resume, and filament change macros to ensure all move commands have complete values.
  3. Set default values for macro parameters and convert them to numbers before use, e.g., params.Z|default(10)|float.
  4. Ensure the slicer units are in millimeters and do not output G20.
  5. If the error is Unknown g-code state, check that SAVE_GCODE_STATE NAME= and RESTORE_GCODE_STATE NAME= use the same name.

Related configuration reference: Macros.

Must home axis first​

Error Message: The axis has not been homed and cannot execute the current move command.

Common Causes:

  • G28 has not been executed after power-on or FIRMWARE_RESTART.
  • A macro executes a move command before executing a homing command.
  • The machine state is reset after a print pause, resume, or cancel.
  • Abnormal configuration of homing macros, probe macros, or sensorless homing causes Klipper to not correctly record 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 command.
  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 the driver current, sensitivity, and homing_retract_dist.

Related configuration reference: Homing and Direction Calibration Guide, Sensorless Homing.

Endstop still triggered after retract​

Error Message: After homing triggers the endstop, the endstop is still triggered when the retract distance is completed.

Common Causes:

  • The normally open/normally closed logic of the endstop switch is configured inversely.
  • The endstop switch is stuck, damaged, or has incorrect wiring.
  • homing_retract_dist is too small; the axis does not clear the endstop after retracting.
  • Sensorless homing sensitivity is too high, causing it to still be considered triggered after retracting.
  • Incorrect configuration of the driver enable_pin, motor direction, or endstop pin, causing abnormal homing behavior.

Solutions:

Power Off Operation

Before checking endstop connectors, motor wiring, or reseating cables, fully turn off the printer and disconnect the power supply. When testing while powered, only operate via web commands and manually trigger the endstop mechanically. Do not touch terminals.

  1. Execute QUERY_ENDSTOPS to confirm the status is open when not triggered and TRIGGERED when manually triggered.
  2. If the status is opposite, adjust the ! prefix before the endstop pin.
  3. Power off and check the mechanical state of the endstop switch, wiring, and connector.
  4. Appropriately increase homing_retract_dist and test again.
  5. If using sensorless homing, reduce sensitivity and ensure the homing current is appropriate.

Related configuration reference: Endstops, Sensorless Homing.

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 messages indicating the endstop was not triggered.

Common Causes:

  • The homing direction is configured incorrectly, making the motor 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, and the homing distance is insufficient.
  • Sensorless homing sensitivity is too low; the axis hits the mechanical end but is not detected as triggered.
  • The motor wiring or direction configuration is wrong, causing the axis to move in the opposite direction.

Solutions:

  1. Execute QUERY_ENDSTOPS. Manually press the endstop to confirm the status changes from open to TRIGGERED.
  2. Move the axis a short distance to confirm its direction, then check if the ! prefix before dir_pin needs adjustment.
  3. Confirm that homing_positive_dir matches the direction where the endstop is located.
  4. Check if position_endstop, position_min, position_max match the actual mechanical travel.
  5. In sensorless homing scenarios, reduce homing speed and adjust TMC sensitivity.

Related configuration reference: Homing and Direction Calibration Guide, Endstops.

Probe and Leveling Issues​

Power Off Operation

Before checking the wiring, connectors, or pinout of probes like BLTouch, Probe, TAP, Klicky, EDDY, etc., fully turn off the printer and disconnect the power supply. When powered, only execute query commands or observe the 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.

Error Cause:

  • The probe's default state after power-on or reset is TRIGGERED.
  • Incorrect probe wiring or poor contact causes the signal to be permanently triggered.
  • Mechanical failure of the probe, e.g., a BLTouch probe stuck and unable to retract.
  • The Z-axis is already at its lowest position, pressing the probe.

Solutions:

  1. Execute QUERY_PROBE to confirm the status should be open when not touching the bed.
  2. Execute QUERY_ENDSTOPS to confirm the endstop/probe signals are correct.
  3. For BLTouch: BLTOUCH_DEBUG COMMAND=pin_up to ensure the probe is retracted, then QUERY_PROBE to confirm.
  4. Check the current Z-axis position. Lift the Z-axis if necessary.
  5. Power off and check the probe wiring and sensor_pin configuration.

Related configuration reference: Endstops, Common Debug Commands.

No trigger on probe after full movement​

Error Message: The probe did not trigger during the complete probing stroke.

Common Causes:

  • Incorrect probe wiring, power supply, or pin configuration.
  • The probe's mounting height is inappropriate; it cannot trigger within the probing stroke.
  • Incorrect Z-axis direction, probe offset, or leveling area configuration.
  • The probe itself is faulty, or its cable has poor contact during movement.

Solutions:

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

Related configuration reference: Endstops, 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 several samples exceeds samples_tolerance.
  • The bed, gantry, hotend, or probe is not securely fixed, causing wobble during probing.
  • The probe speed is too high, or the probing/retraction distance is inappropriate.
  • Inductive, eddy current, or load cell 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 the speed in the [probe] section and appropriately increase sample_retract_dist.
  3. Temporarily relax samples_tolerance for testing, e.g., 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 only occurs in a specific area, check the bed surface, magnet sheet, cable drag, and probe offset in that area.

Related configuration reference: 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 first executing G28.
  • The macro calling the leveling command does not ensure XY/Z are homed beforehand.
  • After FIRMWARE_RESTART, emergency stop, or error recovery, Klipper has cleared the homed state.

Solutions:

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

Related configuration reference: Homing and Direction Calibration Guide, Macros.

BLTouch failed to verify sensor state​

Error Message: BLTouch failed to verify sensor state; retrying. Error occurs after multiple retries.

Common Causes:

  • Counterfeit/clone BLTouch cannot pass Klipper's internal sensor verification.
  • The sensor_pin is not configured with a pull-up resistor (missing ^ prefix).
  • Incorrect wiring for the BLTouch control or sensor pins.
  • Probe self-test fails, indicated by a blinking red light.

Solutions:

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

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

    pin_up_touch_mode_reports_triggered: False

  3. Ensure the sensor_pin is configured with a pull-up resistor, e.g., sensor_pin: ^PC4.

  4. Check if the BLTouch self-test is normal: After power-on, the probe should extend and retract several times, and the red light should be solid.

BLTouch failed to raise probe​

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

Common Causes:

  • Older version clone BLTouch cannot report the probe retracted state.
  • The probe is mechanically stuck, the magnetic core has shifted, or screws are loose.
  • Incorrect control_pin wiring or configuration.

Solutions:

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

  2. If the action is normal but the error persists, add this to the [bltouch] section:

    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 the powered device.

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 greater than the horizontal_move_z in the leveling configuration.
  • After changing the nozzle, probe mount, or hotend, the probe mounting height changed significantly.
  • horizontal_move_z or z_offset is configured redundantly in multiple include files.

Solutions:

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

Related configuration reference: 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.

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

Solutions:

  1. If you need a 7x7, 9x9, or denser grid, set this in the [bed_mesh] section:

    algorithm: bicubic

  2. If a dense grid is not needed, 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 point count and algorithm match.

  4. After modification, save and execute RESTART.

Related configuration reference: Macros.

bed_mesh: Unknown profile​

Error Message: bed_mesh: Unknown profile [xxx] or a prompt that the profile cannot be found when loading a bed mesh configuration.

Common Causes:

  • The start G-code or macro executes BED_MESH_PROFILE LOAD=xxx, but a profile with that name has never been saved.
  • BED_MESH_CLEAR was executed, or the bed mesh data in the auto-saved section was deleted.
  • SAVE_CONFIG was not executed after completing the bed mesh calibration.
  • Profile names have inconsistent capitalization or spaces.

Solutions:

  1. Execute BED_MESH_OUTPUT or check the auto-saved section at the end of the configuration to see the existing profile names.
  2. If the required profile does not exist, re-run BED_MESH_CALIBRATE, then execute SAVE_CONFIG.
  3. Modify BED_MESH_PROFILE LOAD= in the start G-code to match the actual saved profile name.
  4. If you re-probe before every print, you can remove the unnecessary profile loading command.

Related configuration reference: Macros.

bed_mesh Advanced Configuration Errors​

Error Message: 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.

Common Causes:

  • fade_target is outside the current mesh Z range, or the mesh data has excessive overall deviation.
  • mesh_min, mesh_max, zero_reference_position fall within a non-probable area after calculation with the probe offset.
  • faulty_region covers the zero reference point, preventing Klipper from probing the reference position.
  • Coordinate list format is incorrect, missing commas, or using Chinese punctuation.
  • MESH_MIN / MESH_MAX passed by the adaptive bed mesh macro do not match the machine dimensions or probe offset.

Solutions:

  1. Check mesh_min, mesh_max, probe_count, fade_start, fade_end, and fade_target in the [bed_mesh] section.
  2. If you are unsure about the meaning of fade_target, it is safest to delete this item and let Klipper use the default behavior.
  3. Ensure all probing points, after adding the x_offset / y_offset from the [probe] section, are still within the machine's movable range.
  4. If zero_reference_position or faulty_region is configured, confirm the zero reference point is not within the faulty region.
  5. When an adaptive bed mesh error occurs, first test with fixed mesh_min / mesh_max to ensure the basic bed mesh configuration is working correctly, then restore the macro.

Related configuration reference: Macros, Machine Calibration.

Z_TILT_ADJUST / QUAD_GANTRY_LEVEL Errors​

Error Message: Z_TILT_ADJUST: Point X,Y not reachable with current probe offset, QUAD_GANTRY_LEVEL: Max adjustment X.XXXX exceeds limit, or the gantry deviation is still too large after leveling.

Common Causes:

  • The probe offset configuration is incorrect, causing the calculated probing point to be outside the bed area.
  • The gantry deviation for multiple Z-axes exceeds the max_adjust limit.
  • Z-axis motor directions are inconsistent, causing the gantry to tilt in the opposite direction.
  • Endstop switch mounting heights are inconsistent, resulting in vastly different starting positions for each Z-axis after homing.
  • The gantry mechanical structure is loose, belts are slipping, or lead screw nut clearance is excessive.

Solutions:

Power Off Operation

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

  1. Check x_offset and y_offset in the [probe] section, as well as points in the [z_tilt] or [quad_gantry_level] section.
  2. If the deviation exceeds max_adjust, fully power off, manually level the gantry roughly, then power on, home, and execute leveling.
  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 switches at each corner of the gantry are mounted at the same height, check lead screw nuts, timing belt tension, and couplings for slippage.
  5. If the max_adjust limit is simply too small, you can increase the value appropriately, but not to more than 2-3 times the default value.

Related configuration reference: Homing and Direction Calibration Guide.

Loading...