Troubleshooting

Troubleshooting

This page collects common problems and warnings that are easy to miss when reading the setup pages separately.

The Calibrated G-Code Offset Disappears

Warning: With the default offset path, do not run CALIBRATE_Z inside SAVE_GCODE_STATE and RESTORE_GCODE_STATE.

RESTORE_GCODE_STATE restores the previous G-code offset, so it also removes the offset that CALIBRATE_Z just applied.

The First Layer Changes After Homing

Warning: Do not home Z after CALIBRATE_Z. Homing Z establishes a new reference point, so the calibration must be run again after any later Z home.

The Offset Is Large or Outside the Margins

Start from a reasonable manual Z offset and a safe stepper_z:position_endstop. The plugin is intended to make a small automatic correction, not compensate for a badly configured Z reference.

If CALIBRATE_Z reports a possible new position_endstop, treat it as a suggestion only. Verify the setup mechanically and with slow manual moves before changing the configuration.

Note: Use offset_margins to keep unexpected calculated offsets from being applied.

The Probe Is Reported as Not Attached

The probe should be configured as normally closed so Klipper can detect whether it is attached. If calibration stops before probing with the magnetic probe, check:

• The attach macro.
• start_gcode and before_switch_gcode.
• Probe wiring and trigger state.
• Whether the probe is physically attached before magnetic probe probing starts.

CALCULATE_SWITCH_OFFSET Reports a Negative Result

switch_offset must be positive. A negative calculated value usually means the nozzle is still too far from the bed or the switch body measurement is wrong.

Check the Z endstop, the endstop rod, and the position where the switch body touches the endstop.

Warning: Do not drive the endstop pin directly onto the switch actuator. Touch the switch body in a repeatable way instead.

Adaptive Mesh Results Look Wrong

When using bed mesh, calibrate at the mesh zero_reference_position or pass the correct BED_POSITION to CALIBRATE_Z.

Warning: Adaptive mesh macros may change the mesh area and zero reference at runtime. Make sure the calibration point matches the mesh that will be used for the print.

Nozzle Probing Is Inconsistent

Check for nozzle ooze before changing calibration math. Material on the nozzle can affect any nozzle-contact endstop.

See Ooze Mitigation.

For setup constraints that are not specific to one failure message, see Known Limitations.

Probe Docking Fails After Calibration

If the probe docks to the bed and the default offset path is used, a large applied G-code offset can affect the docking height.

Reset the G-code offset inside the attach or dock macro, then restore the previous state:

SAVE_GCODE_STATE NAME=YOUR_MACRO_NAME
SET_GCODE_OFFSET Z=0.0

your macro content here...

RESTORE_GCODE_STATE NAME=YOUR_MACRO_NAME

offset_gcode Macro Does Not See the Offset

offset_gcode receives the calculated correction as params.Z. If the hook calls another macro, that value is not forwarded automatically.

Use:

[z_calibration]
offset_gcode:
    _APPLY_Z_CALIBRATION_OFFSET Z={params.Z}

Not:

[z_calibration]
offset_gcode:
    _APPLY_Z_CALIBRATION_OFFSET

The same rule applies to error_gcode: pass ERROR="{params.ERROR}" when calling another macro that needs the error text.

Reset Does Not Work With Custom offset_gcode

SET_GCODE_OFFSET Z=0.0 resets the default G-code offset path. If offset_gcode changes another state, such as kinematic position, reset that custom state with a matching printer-specific procedure.