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, plugs, or wire sequence of probes such as BLTouch, Probe, TAP, Klicky, EDDY, etc., please 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 wiring harnesses.
Probe triggered prior to movement
Error message: Before homing or probing movement begins, the probe is already in a triggered state.
Causes:
- The probe's default state after power-on or reset is
TRIGGERED. - Incorrect probe wiring sequence or poor contact causes the signal to remain in a triggered state.
- Probe mechanical failure, such as the BLTouch probe being stuck and unable to retract.
- The Z axis is already at its lowest position, causing the probe to be pressed.
Solutions:
- Execute
QUERY_PROBEto confirm that the state should beopenwhen not contacting the bed. - Execute
QUERY_ENDSTOPSto confirm whether the endstop/probe signal is correct. - For BLTouch:
BLTOUCH_DEBUG COMMAND=pin_upto ensure the probe retracts, thenQUERY_PROBEto confirm. - Check the current Z-axis position; if necessary, raise the Z axis first.
- After powering off, check the probe wiring and
sensor_pinconfiguration.
Related configuration references: Endstop Related, Common Debug Commands.
No trigger on probe after full movement
Error message: The probe did not trigger within the full probing travel.
Common causes:
- Incorrect probe wiring, power supply, or pin configuration.
- Improper probe installation height, making triggering impossible within the probing travel.
- Incorrect Z-axis direction, probe offset, or leveling area configuration.
- Probe body failure, or poor wiring harness contact during movement.
Solutions:
- Execute
QUERY_PROBE, manually trigger the probe, and confirm that the state changes normally. - After powering off, check the probe power supply, signal wire, and configured pin.
- Check the probe installation height and confirm that the probe is within triggerable range before probing.
- Check whether the probe points in
[probe],[bed_mesh],[z_tilt], or[quad_gantry_level]exceed the bed. - If the problem only occurs at certain positions, focus on checking wiring harness drag and probe offset.
Related configuration references: Endstop Related, Macro Introduction.
Probe samples exceed samples_tolerance
Error message: Probe samples exceed samples_tolerance, or Probe samples exceed tolerance. Retrying... repeatedly appears in the log.
Common causes:
- Poor probe repeatability, with the Z-height difference among several samples exceeding
samples_tolerance. - The bed, gantry, hotend, or probe is not firmly secured, causing shaking during probing.
- Probe speed is too fast, or the probing distance/retract distance is inappropriate.
- Inductive, eddy current, or pressure sensors are affected by temperature drift or electromagnetic interference.
Solutions:
- Check whether the probe, hotend, bed plate, and gantry structure are firmly secured.
- Reduce
speedin[probe], and appropriately increasesample_retract_dist. - Temporarily loosen
samples_tolerancefor testing first, for example 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 only occurs in a certain area, check the bed surface, magnetic sheet, wiring harness drag, and probe offset in that area.
Related configuration references: 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_LEVELbefore executingG28. - The macro calls a leveling command without ensuring that XY/Z have been homed.
- After
FIRMWARE_RESTART, an emergency stop, or error recovery, Klipper has cleared the homing state.
Solutions:
- Execute
G28first, then execute the probe or leveling command. - Add a homing check at the beginning of the leveling macro, or directly add
G28. - If using an independent Z probe, confirm that
endstop_pin: probe:z_virtual_endstopand the[probe]configuration are complete.
Related configuration references: Homing and Direction Calibration Guide, Macro Introduction.
BLTouch failed to verify sensor state
Error message: BLTouch failed to verify sensor state; retrying. Error occurs after multiple retries.
Common causes:
- Pirated/cloned BLTouch cannot pass Klipper's internal sensor verification.
sensor_pinis not configured with a pull-up resistor (missing the^prefix).- Incorrect wiring of the BLTouch control pin or sensor pin.
- Probe self-test failure, with the red light blinking.
Solutions:
-
First run
BLTOUCH_DEBUG COMMAND=pin_down,BLTOUCH_DEBUG COMMAND=touch_mode, andQUERY_PROBEto confirm the state. -
If manual testing passes but automatic homing/probing still reports errors, add the following to
[bltouch]:pin_up_touch_mode_reports_triggered: False -
Ensure that
sensor_pinis configured with a pull-up resistor, such assensor_pin: ^PC4. -
Check whether the BLTouch self-test is normal: after power-on, the probe extends and retracts several times, and a steady red light indicates normal operation.
BLTouch failed to deploy
Error message: BLTouch failed to deploy.
Common causes:
- The BLTouch probe is mechanically stuck and cannot extend.
- Incorrect
control_pinwiring or configuration, so the probe does not receive the deploy signal. - Pirated/cloned BLTouch timing is incompatible.
- Insufficient probe power supply (using the mainboard's 3.3V instead of 5V).
Solutions:
- Manually test probe control:
BLTOUCH_DEBUG COMMAND=pin_down, and observe whether the probe extends. - Confirm that
control_pinandsensor_pinin[bltouch]match the mainboard documentation. - Check whether the BLTouch power supply is 5V (some mainboards require a jumper selection).
- If the probe does not move at all, power off and check the wiring and plugs, 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 successfully retract.
Common causes:
- Older cloned BLTouch versions cannot report the probe retraction state.
- The probe is mechanically stuck, the magnetic core has shifted, or screws are loose.
- Incorrect
control_pinwiring or configuration.
Solutions:
-
Test the probe control function:
BLTOUCH_DEBUG COMMAND=pin_downandBLTOUCH_DEBUG COMMAND=pin_up. -
If movement is normal but an error is reported, add the following to
[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 powered equipment.
Complete guide: For complete configuration instructions on BLTouch wiring, testing, clone compatibility, and output modes, see BLTouch Configuration and Troubleshooting.
Communication timeout during homing
Error message: Communication timeout during homing x, Communication timeout during homing y, etc.
Common causes:
- During homing, the CAN bus is affected by electromagnetic interference generated by motor movement, causing communication packet loss.
- Poor USB communication cable contact, disconnecting when movement causes shaking.
- MCU overload (for example, homing simultaneously triggers a large number of sensor queries).
Solutions:
- Check the routing of the CAN / USB communication cable, ensuring it is away from motor wires, heater wires, and power wires.
- Confirm that the communication cable plugs are secure, and replace them with better-quality shielded cables.
- Confirm that all MCU firmware versions are consistent.
- If it only occurs when homing a specific axis, focus on checking the shielding and grounding of that axis's motor wires and endstop switch wiring 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 leveling configuration. - After replacing the nozzle, probe mount, or hotend, the probe installation height changes significantly.
horizontal_move_zorz_offsetis configured repeatedly in multiple include files.
Solutions:
- Search all
horizontal_move_zandz_offsetentries to confirm the configuration that ultimately takes effect. - Set the
horizontal_move_zin the relevant leveling configuration to a safe value greater than the probez_offset. - If
z_offsetis abnormally large, recheck the probe installation height and runPROBE_CALIBRATE. - After saving, run
RESTART, then retestBED_MESH_CALIBRATEor the leveling command.
Related configuration references: Machine Calibration, Macro 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.
Cause of the error: lagrange interpolation is prone to oscillation with a high number of samples, so Klipper limits the number of probe points per axis to no more than 6 when using this algorithm.
Solutions:
-
If you need a
7x7,9x9, or denser mesh, set the following in[bed_mesh]:algorithm: bicubic -
If you do not need a dense mesh, reduce
probe_countto6,6or less. -
When adaptive bed mesh passes
PROBE_COUNTfrom the slicer or a macro, also confirm that the final point count matches the algorithm. -
After modifying, save and run
RESTART.
Related configuration references: Macro Introduction.
bed_mesh: Unknown profile
Error message: bed_mesh: Unknown profile [xxx], or a prompt that the profile cannot be found when loading bed mesh configuration.
Common causes:
- The start G-code or a macro runs
BED_MESH_PROFILE LOAD=xxx, but that name was never saved. BED_MESH_CLEARwas run, or the bed mesh data in the autosave section was deleted.SAVE_CONFIGwas not run after bed mesh calibration completed.- The profile name differs in case or spaces.
Solutions:
- Run
BED_MESH_OUTPUTor check the autosave section at the end of the configuration to confirm the existing profile names. - If the required profile does not exist, rerun
BED_MESH_CALIBRATE, then runSAVE_CONFIG. - Modify
BED_MESH_PROFILE LOAD=in the start G-code so the name matches the actual saved name. - If the bed is rescanned before every print, you can delete unnecessary profile loading commands.
Related configuration references: Macro 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_targetexceeds the current bed mesh Z height range, or the overall bed mesh data deviation is too large.mesh_min,mesh_max, andzero_reference_position, after accounting for probe offset, fall into an unprobeable area.faulty_regioncovers the zero reference point, preventing Klipper from probing the reference position.- The coordinate list format is incorrect, missing commas, or using Chinese punctuation.
- The
MESH_MIN/MESH_MAXpassed by the adaptive bed mesh macro do not match the machine dimensions and probe offset.
Solutions:
- Check
mesh_min,mesh_max,probe_count,fade_start,fade_end, andfade_targetin[bed_mesh]. - If you are not clear about the meaning of
fade_target, delete this item first 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 that the zero reference point does not fall within the faulty region. - When an adaptive bed mesh error occurs, first test with fixed
mesh_min/mesh_max, confirm the basic bed mesh configuration is normal, and then restore the macro.
Related configuration references: Macro 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 the deviation is still too large after gantry leveling.
Common causes:
- The probe offset configuration is incorrect, causing the calculated probe points to exceed the bed range.
- The gantry deviation of multiple Z axes exceeds the range allowed by
max_adjust. - The Z-axis motor directions are inconsistent, causing the gantry to tilt in opposite directions.
- The limit switch installation heights are inconsistent, resulting in large differences in the starting position of each Z axis after homing.
- The gantry mechanical structure is loose, the belt slips, or the lead screw nut clearance is too large.
Solutions:
Before manually adjusting the Z lead screws, timing belts, couplings, or checking the gantry limit installation, completely turn off the printer and disconnect the power supply. Do not forcibly rotate the lead screws or timing belts while the motors are powered and holding torque.
- Check
x_offsetandy_offsetin[probe], as well aspointsin[z_tilt]or[quad_gantry_level]. - If the deviation exceeds
max_adjust, completely power off, manually adjust the gantry to approximately level, then power on again, home, and run leveling. - Run
STEPPER_BUZZ STEPPER=stepper_zandSTEPPER_BUZZ STEPPER=stepper_z1(use the actual names) to confirm that each Z motor moves in the same direction individually. - After powering off, check whether the limit switch installation heights at each corner of the gantry are consistent, and whether the lead screw nuts, belt tension, and couplings are slipping.
- If only the
max_adjustlimit is too small, you can appropriately increase this value, but do not exceed 2-3 times the default value.
Related configuration references: Homing and Direction Calibration Guide.
no samples between time
Error message: no samples between time X.X and X.X, usually appears after running BED_MESH_CALIBRATE.
Common causes:
- The firmware version of a streaming sampling probe such as an EDDY eddy current probe or Cartographer does not match the host Klipper.
- The probe data stream is interrupted during bed mesh sampling (CAN communication jitter, insufficient USB bandwidth).
- After upgrading Klipper, the probe module firmware was not updated in sync.
- The host CPU load is too high, causing abnormal timestamps in the sampled data.
Solutions:
- Confirm that the firmware version of the probe module (EDDY, Cartographer, etc.) matches the current Klipper version, and reflash the probe firmware if necessary.
- Check the CAN bus status and confirm that
bytes_retransmitandbytes_invalidare not continuously increasing. - Temporarily disable the camera, KlipperScreen, and other high-load services, then rerun bed mesh calibration.
- If the error only occurs in a specific area, check whether that area exceeds the probe's effective sensing range.
- Try reducing the bed mesh sampling speed (decrease the
speedparameter) and retest.
EDDY probe related: EDDY Issue Collection
SVD did not converge in Linear Least Squares
Error message: numpy.linalg.LinAlgError: SVD did not converge in Linear Least Squares, usually triggering shutdown after running BED_MESH_CALIBRATE or ACCEPT.
Common causes:
- Bed mesh sampling point data is abnormal (all identical, contains NaN, or has extreme jumps), and numpy cannot complete the matrix fitting.
- The probe triggers abnormally during sampling (such as EDDY data stream interruption or Cartographer exceeding the model range).
- There is metal foreign matter on the bed surface or contamination on the probe sensing surface, causing individual point readings to deviate severely.
- The host numpy version is too old or the installation is corrupted. Solution:
- Re-run
BED_MESH_CALIBRATEand observe whether it fails at the same point every time. - Check whether the bed surface is clean and whether there is residual filament or metal debris on the probe sensing surface.
- If the probe is EDDY / Cartographer, confirm that the firmware version matches Klipper, and check the stability of CAN communication.
- Try reducing
probe_count(for example, from 7x7 to 5x5) and then retest to rule out the effect of a single-point anomaly. - If the problem persists, try updating the host numpy:
pip install --upgrade numpy. - Check whether there are preceding errors in
klippy.logbefore the error, such asToolhead stopped outside model rangeor probe timeout.