Probe Calibration Tool

Klipper's probe Z offset, Z endstop, bed mesh, and Delta calibration commands all ultimately enter the same manual probing flow. It is provided by the manual_probe module, which Klipper loads automatically: it does not need to be written in printer.cfg and has no configurable options. What you actually configure is [probe] (or [bltouch]) and [stepper_z].

Most prompts from this flow are only waiting for you to enter TESTZ; they are not faults. Only the three below actually invalidate a calibration or prevent a command from starting.

Quick Reference

Terminal prompt	Nature	What to do
Starting manual Z probe…	Normal prompt, waiting for input	TESTZ Z=-0.1 to approach downward → ACCEPT; use ABORT to give up
Manual probe failed!…	This calibration is void (no shutdown, no config write)	Re-run the calibration command; do not move X/Y at all, and the final Z must be lower than at the start
Already in a manual Z probe…	Command-level error	ABORT the old session first, or end the other tool that holds ACCEPT

Probe hardware and configuration errors (Probe triggered prior to movement, No trigger on probe, Probe samples exceed samples_tolerance, BLTouch, bed_mesh) are covered in Motion, endstop, and leveling errors.

Which Commands Start Manual Probing

Command	Purpose	Manual probing
MANUAL_PROBE	Measure the Z of a point with the paper method when there is no probe	Always
PROBE_CALIBRATE	Calibrate the probe z_offset	Fine adjustment after probing
Z_ENDSTOP_CALIBRATE	Calibrate position_endstop	Always; only exists when [stepper_z] defines position_endstop, machines that use the probe as the Z endstop (probe:z_virtual_endstop, e.g. TAP) do not have this command
DELTA_CALIBRATE	Delta tower height / radius	When there is no probe or METHOD=manual
BED_MESH_CALIBRATE, BED_TILT_CALIBRATE, Z_TILT_ADJUST, QUAD_GANTRY_LEVEL	Bed mesh / tilt / multi-Z probing	When METHOD=manual is added

Interface dialog

The calibration dialog in Mainsail / Fluidd reads the manual_probe state; clicking ACCEPT is equivalent to entering ACCEPT in the terminal.

TESTZ Usage

Form	Behavior
TESTZ Z=-0.1	Move by the given value, not limited by the step size (use it to close a large gap in one move)
TESTZ Z=- / --	Bisect / jump to a lower probed point, step ≤ 0.2mm
TESTZ Z=+ / ++	Bisect / jump to a higher probed point, step ≤ 0.2mm

Two things to know

• + / - / ++ / -- move at most 0.2mm per command; if that is too slow, use the numeric form.
• Each TESTZ first lifts to "target + 0.5mm" and then descends to the target, so the nozzle rising slightly mid-move is normal.

The Three Prompts in Detail

Starting manual Z probe

// Starting manual Z probe. Use TESTZ to adjust position.
// Finish with ACCEPT or ABORT command.
// Z position: ?????? --> 5.000 <-- ??????

Normal prompt; the state is still ready, and it neither ends on its own nor times out. The value between --> and <-- is the current Z; the left and right sides are the lower / higher positions already probed, and ?????? means nothing has been recorded in that direction yet.

What to do: step down following the paper test flow, and ACCEPT on contact.

Manual probe failed!

// Manual probe failed! Use TESTZ commands to position the
// nozzle prior to running ACCEPT.

The calibration is void: no shutdown is triggered, but no configuration is written, ACCEPT / TESTZ / ABORT stop working, and the calibration command must be re-run (clicking SAVE_CONFIG at this point is meaningless).

There are only two causes, and either one fails it:

• X/Y moved: a joystick / arrow key was used during the session, or a macro contains G1 X.. Y.., or Klicky's dock move.
• Z was not lower: you only moved up, or probed too far down and lifted back to the starting point; the check only looks at Z at the moment ACCEPT is pressed, regardless of the motion in between (even 0.01mm higher fails).

Resolution:

1. Re-run the calibration command and approach in one direction, downward with TESTZ Z=-0.1 (-0.05 when close); confirm the middle Z position value is smaller than at the start, then ACCEPT.
2. Do not touch X/Y during the session.
3. If it fails immediately every time, check whether the starting height is too low, depending on the structure:
   • Machines with a dedicated Z endstop: check [stepper_z] position_endstop.
   • Using the probe as the Z endstop (probe:z_virtual_endstop, nozzle-triggered structures such as Voron TAP): [stepper_z] has no position_endstop; check [probe] z_offset and the Z axis lower limit position_min.
   • Delta machines: also check minimum_z_position.

Already in a manual Z probe

Already in a manual Z probe. Use ABORT to abort it.

Command-level error: before starting a new session, Klipper finds that ACCEPT is already taken.

Common causes: the previous session did not finish with ACCEPT / ABORT; tools such as BED_SCREWS_ADJUST also hold ACCEPT; a custom gcode_macro has the same name as a built-in command.

Resolution:

1. Run ABORT to end the old session. If it reports Unknown command: ABORT, there is no session; end the tool that actually holds ACCEPT instead (e.g. run ADJUSTED in BED_SCREWS_ADJUST).
2. If it happens every time, check all include files for a macro with the same name as a built-in command, rename or delete it, and retry.
3. Refreshing the interface or restarting Klipper clears the stale calibration dialog in the UI.

After ACCEPT

• MANUAL_PROBE replies Z position is <value>; PROBE_CALIBRATE and Z_ENDSTOP_CALIBRATE give a suggested new value.
• You must run SAVE_CONFIG (or SAVE_CONFIG & Restart in the interface) for the setting to be written and take effect after a restart.
• To give up midway, use ABORT: no configuration is written, and Manual probe failed! is not triggered.

Standard Paper Test Flow

Motion hazard

The nozzle moves down automatically during calibration. Before starting, move hands and tools away, make sure nothing obstructs below the nozzle and nothing is left on the heatbed, and be ready to emergency-stop at any time.

1. Home the printer and move the nozzle directly above the point to calibrate.
2. Run the calibration command and confirm that Starting manual Z probe appears.
3. Place the paper between the nozzle and the heatbed and slide it back and forth.
4. Lower it gradually with TESTZ Z=-0.1; when close, switch to TESTZ Z=-0.05 or Z=- for finer steps.
5. Stop when the paper is lightly pinched and drags with clear resistance.
6. Run ACCEPT; if it reports Manual probe failed!, troubleshoot per that entry and redo.
7. Run SAVE_CONFIG to save and restart.

Approach from one direction only

Always approach the contact point from above; this reduces Z axis backlash error and also avoids failing because Z is not lower than the starting height.

Related Documentation

Probe and leveling errors: Motion, endstop, and leveling errors · BLTouch: BLTouch configuration and troubleshooting · EDDY: EDDY issue collection · Load Cell: Load Cell probe troubleshooting

Common debugging commands: Common debugging commands · Machine calibration flow: Machine calibration