Known Limitations

Known Limitations

This page lists constraints and behaviors that are important before using automatic Z calibration in a print start macro.

Firmware Support

The plugin supports Klipper and Kalico. Kalico installations use the external plugin mechanism in klippy/plugins.

Warning: Kalico users must enable [danger_options] allow_plugin_override: True before loading the plugin.

Repository Checkout Required

The installer links only z_calibration.py into Klipper or Kalico. Helper modules load from the repository checkout through that symlink target.

Warning: Keep the cloned klipper_z_calibration repository in place after installation.

Moonraker Channel Migration

New installer-created Moonraker update manager sections use channel: stable.

Normal Moonraker updates do not rerun the installer, so existing [update_manager z_calibration] sections without a channel are not migrated automatically. Rerun install.sh or manually add channel: stable to moonraker.conf and restart Moonraker.

Physical Z Endstop Required

The plugin requires a physical Z endstop triggered by the nozzle. A virtual probe pin is not supported as the Z endstop.

See Requirements before installing.

Dockable Contact Probe Required

The plugin is intended for dockable contact probes such as Klicky-style probes.

Unsupported probe types include BLTouch-style probes, Beacon-style probes, and other non-dockable or virtual probe implementations.

Probe Check Timing

When the probe is configured as normally closed, the plugin checks whether the magnetic probe is attached before probing with it.

Note: The printer may already have moved to the switch or bed probing position before this check fails.

G-Code Offset Scope

Without offset_gcode, CALIBRATE_Z applies the result with SET_GCODE_OFFSET. Commands that restore a previous G-code state can restore the previous offset too.

Warning: With the default offset path, do not wrap CALIBRATE_Z in SAVE_GCODE_STATE and RESTORE_GCODE_STATE; the calibrated offset will be lost when the state is restored.

Custom offset_gcode Scope

When offset_gcode is configured, the plugin does not call the built-in SET_GCODE_OFFSET path. The hook receives the calculated correction as params.Z and must apply the complete correction itself.

Warning: If offset_gcode calls another macro, forward the value explicitly, for example MY_OFFSET_MACRO Z={params.Z}. A bare macro call does not provide params.Z to the called macro.

Z Homing After Calibration

Z calibration is relative to the current homed Z reference.

Warning: Do not home Z after CALIBRATE_Z. If Z is homed again, run CALIBRATE_Z again.

Nozzle Ooze

Nozzle-contact probing can be affected by material on the nozzle. Ooze can change the measured nozzle height during repeated probes.

See Ooze Mitigation for practical options.

Adaptive Mesh Macros

Adaptive mesh macros can change the mesh area and zero reference position at runtime.

Warning: Make sure CALIBRATE_Z uses the same reference point as the mesh that will be used for the print. Use BED_POSITION when a macro needs to override the configured bed position.

Removed Configuration Options

Current refactored releases no longer support these old plugin configuration options:

• Use offset_margins instead of max_deviation.
• Use safe_z_height instead of clearance.

The plugin can still read older Klipper bed mesh relative-reference data when Klipper exposes it, but new configurations should use zero_reference_position.

See Configuration for current configuration guidance.