Motion, Limit, and Leveling Errors
This page compiles errors related to movement range, homing, endstops, probes, bed meshing, and multi-Z leveling. When involving wiring, connectors, or manual mechanical adjustments, please power off the device before proceeding.
Move out of range
Error message: The target coordinate exceeds the motion range allowed by Klipper. The log usually shows something like Move out of range: X Y Z [E].
Common causes:
- The machine dimensions in the slicer do not match
position_min/position_maxin the Klipper configuration. - The start G-code, end G-code, filament change macro, or pause macro moves outside the machine range.
- After using skew correction, probe offset, or bed mesh configuration, the actual calculated coordinates become negative or exceed the maximum travel.
- The model height exceeds the Z-axis maximum travel.
Solutions:
- Determine which axis is out of range based on the coordinates in the error.
- Check the
position_min,position_max, and slicer machine dimensions for the corresponding axis. - Check the parking coordinates in macros like start, end, pause, and filament change, avoiding parking at
0,0or the maximum boundary. - If the error occurs during bed probing, check the
mesh_min,mesh_max, and probe offset in[bed_mesh]. - Save the configuration, restart Klipper, and re-test.
Related configuration references: Macro Introduction, 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 Zis missing the specific coordinate value. - A macro variable is empty, resulting in a final move command lacking
X,Y,Z,E, orFvalues. - Formatting errors (line breaks, curly braces, variable names, or escape sequences) in the slicer's start/end G-code.
- The
Fspeed parameter is empty, zero, or not a number. - The G-code file uses inch mode
G20, which Klipper does not support. - The
SAVE_GCODE_STATE/RESTORE_GCODE_STATEnames used in macros are inconsistent.
Solutions:
- Find the complete error line in
klippy.logto identify whichG1,G0, or state command is failing. - Check the slicer's start, end, pause, resume, and filament change macros to ensure all move commands have complete values.
- Set default values for macro parameters and convert them to numbers before use, e.g.,
params.Z|default(10)|float. - Ensure the slicer units are millimeters and do not output
G20. - If the error is
Unknown g-code state, check thatSAVE_GCODE_STATE NAME=andRESTORE_GCODE_STATE NAME=use the same name.
Related configuration references: Macro Introduction.
Must home axis first
Error message: The axis has not been homed, so the current move command cannot be executed.
Common causes:
G28was not executed after power-on orFIRMWARE_RESTART.- A macro executes a move command before executing the homing command.
- The machine state is reset after a print is paused, resumed, or cancelled.
- Abnormal configuration of homing macros, probe macros, or sensorless homing prevents Klipper from correctly recording the homed state.
Solutions:
- Manually execute
G28before moving the corresponding axis. - Check the start G-code and macros to ensure homing is completed before any move commands.
- If Klipper or firmware was recently updated, check if the homing-related macros are still compatible with the current version.
- If using sensorless homing, check the 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 homing triggers the endstop, the endstop remains triggered when the retract distance is completed.
Common causes:
- The endstop switch normally open/normally closed logic is configured incorrectly.
- The endstop switch is stuck, damaged, or has incorrect wiring.
homing_retract_distis too small, keeping the switch pressed after retraction.- The sensitivity for sensorless homing is too high, so it is still considered triggered after retraction.
- Incorrect configuration of driver
enable_pin, motor direction, or endstop pin, causing abnormal homing behavior.
Solutions:
Before checking endstop connectors, motor wiring, or re-plugging cables, completely turn off the printer and disconnect it from the power supply. When testing with power on, only operate web commands and mechanically trigger the endstop; do not touch terminals.
- Run
QUERY_ENDSTOPS. Confirm the endstop showsopenwhen not triggered andTRIGGEREDwhen manually triggered. - If the state is reversed, adjust the
!before the endstop pin. - Power off and check the endstop switch's mechanical state, wiring, and connector.
- Appropriately increase
homing_retract_distand re-test. - If using sensorless homing, lower the sensitivity and confirm 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 prompts indicating the endstop was not triggered.
Common causes:
- The homing direction is configured incorrectly, causing the motor to move away from the endstop.
- The endstop switch is not connected, the connector is loose, or the pin is configured incorrectly.
- The
position_endstop,position_min, andposition_maxconfigurations do not match the actual travel, and the homing distance is insufficient. - The sensitivity for sensorless homing is too low, so hitting the mechanical stop is not recognized as a trigger.
- The motor wiring or direction configuration is incorrect, causing the axis to move in the opposite direction.
Solutions:
- Run
QUERY_ENDSTOPS. Manually press the endstop and confirm the state changes fromopentoTRIGGERED. - Move the axis a small distance to confirm the direction, then check if the
!beforedir_pinneeds adjustment. - Confirm
homing_positive_dirmatches the endstop's location direction. - Check that
position_endstop,position_min, andposition_maxcorrespond to the actual mechanical travel. - In sensorless homing scenarios, lower the homing speed and adjust the TMC sensitivity.
Related configuration references: Homing and Direction Calibration Guide, Endstop Related.
Sensorless Homing Troubleshooting
Sensorless homing uses the DIAG signal from the TMC driver to detect motor stalls, replacing physical endstop switches. Improper configuration or sensitivity can lead to the errors below. For complete compatibility checks, reference configurations, and sensitivity debugging methods, see Sensorless Homing Usage.
Homing Not Triggered: No trigger on x after full movement
Error message: When homing with virtual_endstop, the error No trigger on x after full movement or No trigger on y after full movement appears, and the carriage hits the endpoint without stopping.
Common causes:
- Inappropriate sensitivity threshold:
driver_SGTHRSis too low (not sensitive enough) for TMC2209, ordriver_SGTis too high for TMC5160 / TMC2240 / TMC2130. - For Class B mainboards, the
DIAGjumper cap is not installed, or the corresponding endstop port still has other devices connected. - The
diag_pinlacks the pull-up symbol^, so the open-drain signal cannot trigger stably. - The homing speed is too low, or the driver current is too low, causing insufficient stall current change to trigger the
DIAGsignal.
Before checking jumper caps, endstop port wiring, or plugging/unplugging cables, turn off the printer and disconnect it from the power supply. Do not touch terminals or plug/unplug cables while powered on.
Solutions:
- Follow the method in Sensorless Homing Usage · Sensitivity Test, starting from the highest sensitivity and gradually adjusting
SGTHRS/sgt. - Confirm
diag_pinincludes the^pull-up (e.g.,diag_pin: ^PD9). For drivers with dualDIAGpins like TMC5160, confirm whetherdiag0_pinordiag1_pinis selected. - For Class B mainboards, confirm the
DIAGjumper cap is installed and no other device is connected to the corresponding endstop port. - Appropriately increase the homing current and homing speed, then re-test.
Configuration Error: Unknown pin chip name
Error Message: During startup, it reports Unknown pin chip name 'tmc5160 stepper_x', Unknown pin chip name '^awd', etc., and Klipper cannot enter the ready state.
Common Causes:
- A space is mistakenly used between the driver name and axis name in
endstop_pin, such as writingtmc5160 stepper_x:virtual_endstop; the correct format must use an underscore:tmc5160_stepper_x:virtual_endstop. - The pin name for
diag_pin/diag0_pin/diag1_pinis misspelled or contains illegal characters.
Solutions:
- Check the
endstop_pinin[stepper_x]to ensure the format istmcXXXX_stepper_x:virtual_endstop, with an underscore between the driver name and axis name, not a space. - Use a space inside the driver configuration section name
[tmcXXXX stepper_x], but when referencing it inendstop_pin, use an underscore instead. The two names must correspond. - Verify the spelling of the
diag_pinpin name, allowing only^or!prefixes followed by a valid pin name.
Configuration Error: Could not find any TMC driver config section
Error Message: Could not find any TMC driver config section for 'stepper_x' required by TMC autotuning.
Common Causes:
endstop_pinreferencestmcXXXX_stepper_x:virtual_endstop, but there is no corresponding[tmcXXXX stepper_x]driver section in the configuration, or the driver section name does not match the reference.- The driver section is commented out, misspelled, or the axis name doesn't match.
Solutions:
- Ensure a driver configuration section exists that exactly matches the
endstop_pinreference; for example,endstop_pin: tmc2209_stepper_x:virtual_endstoprequires a[tmc2209 stepper_x]section. - Check if the driver section is commented out or if the axis name is written incorrectly (do not confuse
stepper_xwithstepper_y).
Emergency stop during homing: Homing failed due to printer shutdown
Error Message: The printer enters a shutdown state during homing, reporting Homing failed due to printer shutdown.
Common Causes:
- This is not a fault exclusive to sensorless homing, but rather an emergency stop triggered by another shutdown during the homing process (such as
DIAGsignal jitter causing false triggers, a driver error, or a service restart). - The true cause requires checking the first shutdown error before
Homing failedin theklippy.log.
Solutions:
- Open
klippy.log, search for the firstshutdownerror aboveHoming failed due to printer shutdown, and troubleshoot by the corresponding category. - If the error above is
Can't reset time when stepper active, follow the instructions for System, Performance & Service Errors. - If it's a false trigger caused by
DIAGsignal jitter, check thediag_pinpull-up configuration and jumper caps, and appropriately reduce sensitivity.
Related Documents: Sensorless Usage, No trigger on endstop after full movement, TMC Error Troubleshooting
Probe and Leveling Issues
Before checking the wiring, connectors, or pin assignments of probes like BLTouch, Probe, TAP, Klicky, or EDDY, completely shut down the printer and disconnect the power supply. Only execute query commands or observe status when powered on; do not plug or unplug any wiring harnesses.
Probe triggered prior to movement
Error Message: The probe is already in a triggered state before a homing or probing movement begins.
Error Causes:
- The probe defaults to the
TRIGGEREDstate upon power-up or reset. - Incorrect probe wiring or poor contact causes the signal to remain in a triggered state.
- A mechanical failure of the probe, such as a BLTouch probe stuck and unable to retract.
- The Z-axis is already at its lowest position, causing the probe to be pressed down.
Solutions:
- Execute
QUERY_PROBEto confirm the state isopenwhen not contacting the bed. - Execute
QUERY_ENDSTOPSto confirm the endstop/probe signals are correct. - For BLTouch: execute
BLTOUCH_DEBUG COMMAND=pin_upto ensure the probe retracts, then useQUERY_PROBEto confirm. - Check the current Z-axis position, raise the Z-axis if necessary.
- Power off, then check the probe wiring and
sensor_pinconfiguration.
Related configuration reference: Endstops Related, Common Debug Commands.
No trigger on probe after full movement
Error Message: The probe did not trigger within its full probing stroke.
Common Causes:
- Incorrect probe wiring, power supply, or pin configuration.
- Incorrect probe mounting height, preventing it from triggering within its stroke.
- Incorrect Z-axis direction, probe offset, or leveling area configuration.
- A faulty probe, or a wiring harness that loses contact during movement.
Solutions:
- Execute
QUERY_PROBE, manually trigger the probe, and confirm the state changes correctly. - Power off, then check the probe power supply, signal wires, and configured pins.
- Check the probe mounting height to ensure it is within the triggerable range before probing.
- Check if the probing points in
[probe],[bed_mesh],[z_tilt], or[quad_gantry_level]are outside the bed. - If the problem occurs only at certain positions, focus on checking the wiring harness drag and probe offset.
Related configuration reference: Endstops Related, Macro Introduction.
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, where the Z-height difference between several samples exceeds
samples_tolerance. - Loose bed, gantry, hotend, or probe fixture, causing wobble during probing.
- Probe speed is too high, or the travel distance/retract distance is inappropriate.
- Inductive, eddy current, or pressure sensors are affected by temperature drift or electromagnetic interference.
Solutions:
- Check the stability of the probe, hotend, bed, and gantry structure.
- Reduce the
speedin[probe]and appropriately increasesample_retract_dist. - Temporarily relax
samples_tolerancefor testing, e.g., adjust from0.01to0.03or0.05. - If using an inductive/eddy current probe, wait for the bed and nozzle temperatures to stabilize before leveling.
- If the problem occurs only in a specific area, check the bed surface, magnetic sheet, wiring harness drag, and probe offset in that area.
Related configuration reference: Machine Calibration, Macro Introduction.
Must home before probe
Error Message: Must home before probe.
Common Causes:
- Running
PROBE,BED_MESH_CALIBRATE,Z_TILT_ADJUST, orQUAD_GANTRY_LEVELwithout first executingG28. - The macro calls leveling commands without ensuring XY/Z axes are homed.
- After a
FIRMWARE_RESTART, emergency stop, or error recovery, Klipper has cleared the homed state.
Solutions:
- Execute
G28first, then run the probe or leveling command. - Add a homing check or insert a
G28command at the beginning of the leveling macro. - If using an independent Z probe, ensure
endstop_pin: probe:z_virtual_endstopand[probe]are fully configured.
Related configuration reference: Homing and Direction Calibration Guide, Macro Introduction.
BLTouch failed to verify sensor state
Error Message: BLTouch failed to verify sensor state; retrying. after multiple retries.
Common Causes:
- Pirated/clone BLTouch cannot pass Klipper internal sensor verification.
sensor_pinis not configured with a pull-up resistor (missing^prefix).- BLTouch control pin or sensor pin wiring is incorrect.
- Probe self-test fails, red light blinks.
Solutions:
-
First run
BLTOUCH_DEBUG COMMAND=pin_down,BLTOUCH_DEBUG COMMAND=touch_mode, andQUERY_PROBEto confirm status. -
If manual tests pass but auto-homing/probing still reports errors, add the following in
[bltouch]:pin_up_touch_mode_reports_triggered: False -
Ensure
sensor_pinis configured with a pull-up resistor, e.g.,sensor_pin: ^PC4. -
Check if BLTouch self-test is normal: after power-on, the probe extends and retracts several times; a solid red light indicates normal operation.
BLTouch failed to deploy
Error Message: BLTouch failed to deploy.
Common Causes:
- BLTouch probe is mechanically stuck and cannot extend.
control_pinwiring or configuration is incorrect, and the probe does not receive the extend signal.- Pirated/clone BLTouch timing is incompatible.
- Insufficient power supply to the probe (using the motherboard's 3.3V instead of 5V).
Solutions:
- Manually test probe control:
BLTOUCH_DEBUG COMMAND=pin_down, observe if the probe extends. - Confirm that
control_pinandsensor_pinin[bltouch]match the motherboard documentation. - Check if the BLTouch power supply is 5V (some motherboards require a jumper to select).
- If the probe does nothing at all, power off, check wiring and connectors, and replace the probe module if necessary.
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 status.
- Probe is mechanically stuck, magnetic core displaced, or screw loose.
control_pinwiring or configuration is incorrect.
Solutions:
-
Test probe control functions:
BLTOUCH_DEBUG COMMAND=pin_downandBLTOUCH_DEBUG COMMAND=pin_up. -
If actions are normal but errors persist, add the following in
[bltouch]:pin_up_reports_not_triggered: False -
If the probe is stuck, it is recommended to replace the probe module or contact after-sales support. Do not disassemble the device while powered.
Full Guide: See BLTouch Configuration and Troubleshooting for complete configuration instructions on BLTouch wiring, testing, clone compatibility, and output modes.
Communication timeout during homing
Error Message: Communication timeout during homing x, Communication timeout during homing y, etc.
Common Causes:
- During homing, the CAN bus experiences electromagnetic interference from motor movement, causing communication packet loss.
- USB communication cable has poor contact and disconnects during movement.
- MCU is overloaded (e.g., triggering a large number of sensor queries simultaneously during homing).
Solutions:
- Check the CAN/USB communication cable routing, ensuring it is away from motor wires, heater wires, and power cables.
- Confirm the communication cable connector is secure, and replace it with a better quality shielded cable.
- Ensure all MCU firmware versions are consistent.
- If the error occurs only when homing a specific axis, focus on checking the shielding and grounding of that axis's motor wire and limit switch harness.
Related Troubleshooting: Lost communication with MCU, CAN Error Troubleshooting
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_offsetsaved afterPROBE_CALIBRATEis greater than thehorizontal_move_zin the bed leveling configuration. - After replacing the nozzle, probe mount, or hotend, the probe installation height has changed significantly.
horizontal_move_zorz_offsetis configured redundantly in multiple include files.
Solutions:
- Search for all instances of
horizontal_move_zandz_offsetto confirm the final effective configuration. - Set
horizontal_move_zin the relevant bed leveling configuration to a safe value greater than the probe'sz_offset. - If
z_offsetis abnormally large, re-check the probe installation height and runPROBE_CALIBRATE. - After saving, run
RESTART, then re-testBED_MESH_CALIBRATEor the leveling command.
Related configuration reference: Machine Calibration, Macros Introduction.
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: The lagrange interpolation is prone to oscillation with a high number of samples. Klipper limits the number of probe points per axis to 6 when using this algorithm.
Solutions:
-
If a denser grid like
7x7or9x9is needed, set the following in[bed_mesh]:algorithm: bicubic -
If a dense grid is not required, reduce
probe_countto6,6or below. -
When an adaptive bed mesh passes
PROBE_COUNTvia slicer or macro, also ensure the final point count matches the algorithm. -
After modification, save and run
RESTART.
Related configuration reference: Macros Introduction.
bed_mesh: Unknown profile
Error Message: bed_mesh: Unknown profile [xxx] or a message indicating 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 this name was never saved. BED_MESH_CLEARwas executed, or the bed mesh data in the auto-save area was deleted.SAVE_CONFIGwas not executed after completing bed mesh calibration.- The profile name has mismatched case or spacing.
Solutions:
- Execute
BED_MESH_OUTPUTor check the auto-save area at the end of the configuration to confirm the existing profile name. - If the required profile does not exist, re-run
BED_MESH_CALIBRATE, then runSAVE_CONFIG. - Modify the
BED_MESH_PROFILE LOAD=command in the start G-code so the name matches the actually saved name. - If the bed is re-scanned before every print, unnecessary profile loading commands can be removed.
Related configuration reference: Macros Introduction.
bed_mesh Advanced Configuration Errors
Error Messages: 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_targetis outside the current mesh Z-height range, or the mesh data has a large overall deviation.mesh_min,mesh_max, orzero_reference_position, after calculation with the probe offset, falls into an unprobable area.faulty_regioncovers the zero reference point, preventing Klipper from probing the reference position.- The coordinate list has incorrect formatting, missing commas, or uses Chinese punctuation.
MESH_MIN/MESH_MAXpassed by the adaptive bed mesh macro does not match the machine dimensions or probe offset.
Solutions:
- Check
mesh_min,mesh_max,probe_count,fade_start,fade_end, andfade_targetin[bed_mesh]. - If the meaning of
fade_targetis unclear, preferably delete the item and let Klipper use the default behavior. - Confirm that all probe points, after adding the
x_offset/y_offsetfrom[probe], are still within the machine's movable range. - If
zero_reference_positionorfaulty_regionis configured, confirm the zero reference point is not inside the faulty region. - When an adaptive bed mesh reports an error, first test with fixed
mesh_min/mesh_maxto confirm the basic bed mesh configuration is normal before restoring the macro.
Related configuration reference: Macros Introduction, Machine Calibration.
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 persists after gantry leveling.
Common Causes:
- Incorrect probe offset configuration, causing calculated probing points to fall outside the heat bed range.
- The gantry deviation of multiple Z-axes exceeds the allowable range of
max_adjust. - Inconsistent direction of Z-axis motors, causing the gantry to tilt in the opposite direction.
- Inconsistent installation height of endstops, leading to large differences in the starting positions of each Z-axis after homing.
- Loose gantry mechanical structure, belt slippage, or excessive lead screw nut clearance.
Solutions:
Before manually adjusting Z lead screws, timing belts, couplings, or checking gantry endstop installation, completely shut down the printer and disconnect the power supply. Do not forcibly rotate lead screws or timing belts while the motors are energized and holding torque.
- Check
x_offset,y_offsetin[probe], andpointsin[z_tilt]or[quad_gantry_level]. - If the deviation exceeds
max_adjust, completely power off, manually level the gantry approximately, then re-power, home, and perform leveling. - Execute
STEPPER_BUZZ STEPPER=stepper_zandSTEPPER_BUZZ STEPPER=stepper_z1(use actual names) to confirm each Z motor moves in the same direction individually. - After power off, check if the installation height of the endstops at each corner of the gantry is consistent, and check lead screw nuts, timing belt tension, and couplings for slippage.
- If only the
max_adjustlimit is too small, the value can be appropriately increased, but do not exceed 2-3 times the default value.
Related configuration reference: Homing and Direction Calibration Guide.
no samples between time
Error Message: no samples between time X.X and X.X, typically after executing BED_MESH_CALIBRATE.
Common Causes:
- Firmware version mismatch between streaming probes (e.g., EDDY current probe, Cartographer) and the host Klipper.
- Probe data stream interruption during bed mesh sampling (CAN communication jitter, insufficient USB bandwidth).
- Probe module firmware not updated synchronously after upgrading Klipper.
- High host CPU load causing abnormal sampling data timestamps.
Solutions:
- Ensure the probe module (EDDY, Cartographer, etc.) firmware version matches the current Klipper version, reflash the probe firmware if necessary.
- Check the CAN bus status, confirm
bytes_retransmitandbytes_invalidare not continuously increasing. - Temporarily stop cameras, KlipperScreen, and other high-load services, then re-execute bed mesh calibration.
- If the error occurs only in a specific area, check if that area is outside the probe's effective sensing range.
- Try reducing the bed mesh sampling speed (decrease the
speedparameter) and retest.
Related to EDDY Probe: EDDY Issues Collection
SVD did not converge in Linear Least Squares
Error Message: numpy.linalg.LinAlgError: SVD did not converge in Linear Least Squares, typically triggering a shutdown after executing BED_MESH_CALIBRATE or ACCEPT.
Common Causes:
- Bed mesh sampling point data is anomalous (all identical, contains NaN or extreme jumps), preventing numpy from completing the matrix fitting.
- The probe triggers an anomaly during sampling (e.g., EDDY data stream interruption, Cartographer exceeding model range).
- Metal foreign objects on the heat bed surface or contamination on the probe sensing area cause severe reading deviations at individual points.
- Outdated or corrupt numpy installation on the host.
Solutions:
- Re-execute
BED_MESH_CALIBRATEand observe if it fails at the same point each time. - Check if the heat bed surface is clean and if the probe sensing area has residual filament or metal fragments.
- If using an EDDY / Cartographer probe, confirm the firmware version matches Klipper and check CAN communication stability.
- Try reducing
probe_count(e.g., from 7x7 to 5x5) and retest to rule out single-point anomaly effects. - If the problem persists, try updating numpy on the host:
pip install --upgrade numpy. - Check
klippy.logfor preceding errors likeToolhead stopped outside model rangeor probe timeouts before the reported error.