Voron Advanced Z Tilt and Gantry Leveling — Complete Guide

Calibration Klipper Build

Gantry leveling is the foundation of first-layer quality on any Voron. A misaligned gantry produces inconsistent squish across the bed — perfect on one corner, too high on another, dragging on a third. Voron printers use two different systems depending on the model: Z_TILT_ADJUST (Trident) and QUAD_GANTRY_LEVEL (V2.4). This advanced guide covers both in depth, with probe integration strategies, manual leveling backup procedures, and troubleshooting for the toughest alignment problems. Last updated: May 2025.

Z_TILT_ADJUST vs QUAD_GANTRY_LEVEL

These are not interchangeable. They solve the same problem (gantry-to-bed parallelism) but use different hardware and math:

Z_TILT_ADJUST Configuration (Trident)

The Trident's three Z motors (left rear, right rear, front center) adjust independently to tilt the gantry until it's parallel to the bed. Here's a recommended configuration:

[z_tilt]
z_positions:
    -187, -140, z    # Rear left Z
    -187, 140, z     # Rear right Z
    187, 0, z        # Front Z
points:
    0, 0, 0
    0, 200, 0
    200, 0, 0
speed: 200
horizontal_move_z: 10
retries: 3
retry_tolerance: 0.01

The z_positions are physical locations of each Z leadscrew relative to the bed center (0,0). Adjust for your frame size. The points are where the probe measures — ideally directly above each leadscrew for best accuracy.

Key parameters:

• retries: 3 — allows the algorithm to converge if the first adjustment overshoots
• retry_tolerance: 0.01mm — tighter than default (0.02). Achievable on a well-built Trident
• horizontal_move_z: 10mm — high enough to clear obstacles, low enough to minimize probe travel time

QUAD_GANTRY_LEVEL Configuration (V2.4)

The V2.4's four Z motors operate independently to level the gantry. The Z belt system synchronizes coarse movement; QGL handles fine per-corner adjustment:

[quad_gantry_level]
gantry_corners:
    -150,-150,z
    -150,150,z
    150,-150,z
    150,150,z
points:
    0,0,0
    0,210,0
    210,0,0
    210,210,0
speed: 200
horizontal_move_z: 10
retries: 3
retry_tolerance: 0.01
max_adjust: 2

The gantry_corners define the physical locations of each Z motor. The points are probe measurement locations — ideally one near each corner. max_adjust: 2 limits how far the gantry can tilt per cycle, preventing mechanical binding.

Important: QGL and Z Endstops

On a V2.4, QGL works in two phases:

1. Phase 1: Home all Z with endstops. This establishes a rough reference plane.
2. Phase 2: Probe the bed at four points. Calculate the tilt correction and apply it via Z motor micro-adjustments.

If your Z endstops are not physically level with each other (trammed), QGL will waste adjustment range compensating. Tram the endstops first using a machinist square or drill bit shank.

Probe Integration

Both Z_TILT_ADJUST and QGL require a probe. The probe type affects accuracy and workflow:

Inductive Probe (PL-08N, Omron TL-Q5MC)

Most common on Vorons. Good for Z tilt and QGL. Accuracy is ~0.02mm with repeatable trigger point. Requires the bed surface to be metallic. Does not work with PEI spring steel sheets that have a non-metallic coating on the bottom — you need a bare steel sheet or a metallic target beneath.

Voron TAP

Best-in-class probe for Voron. Nozzle-contact based, so it works on any surface. Accuracy ~0.005mm. TAP eliminates Z-offset drift entirely. Highly recommended for both Z_TILT_ADJUST and QGL. The only downside is the ~20g added toolhead mass and potential clog clearance issues with very soft nozzles (brass).

Klicky Probe

Dockable probe that stays on the toolhead during probing but docks during printing. Less mass than TAP. Accuracy ~0.01mm. Popular for V2.4 builds where minimizing toolhead mass is a priority.

Manual Leveling: The Backup Procedure

Sometimes your printer is so far out of level that automatic routines can't converge. In those cases, you need manual leveling first:

Step 1: Mechanical Tram

Disconnect all Z motors (or disable steppers with M18). Manually turn each Z leadscrew (Trident) or Z belt tensioner (V2.4) until the gantry sits roughly parallel to the frame. Use a digital caliper to measure from gantry to frame top on each corner. Target: within 0.5mm across all corners.

Step 2: Paper Test

Home the toolhead. Place a piece of standard printer paper under the nozzle at each probe point. Lower by 0.05mm increments until the nozzle just grips the paper. Record the Z position at each corner. The variance tells you how much Z tilt/QGL needs to correct.

Step 3: Re-enable and Run

Re-enable motors and run Z_TILT_ADJUST or QGL. If the correction values are under 2mm, your manual tram was successful. If they're over 2mm, you may have mechanical binding — check that Z leadscrews spin freely and Z belts are properly tensioned.

Bed Soak Protocol for Thermal Stability

Here's the critical detail most guides skip: probe at temperature. The bed grows significantly when heated (aluminum bed carriers expand ~0.5-1mm across 300mm). Probing a cold bed and printing on a hot bed means your Z tilt is wrong by the time the print starts.

M140 S105     # Set bed to printing temperature
M106 S255     # Part cooling fan off during soak
G28           # Home all axes
G4 P600000    # Wait 10 minutes (600,000ms)
Z_TILT_ADJUST # Or QUAD_GANTRY_LEVEL
BED_MESH_CALIBRATE
M109 S245     # Heat hotend while probing completes

The 10-minute soak is non-negotiable for ABS/ASA printing at 100-110C. The bed continues to expand measurably for 6-8 minutes after reaching temperature. Probing after stabilization gives repeatable results.

Troubleshooting Common Issues

"Probe triggered prior to movement"

Common with inductive probes. The probe triggers on the bed during the approach move. Increase horizontal_move_z to 15-20mm so the probe approaches the measurement points at a higher Z. If that fails, check that your probe isn't mounted too low — the trigger point should be 2-3mm above the nozzle tip.

Corrections Getting Larger with Each Retry

This indicates mechanical binding. The Z tilt algorithm assumes each step produces consistent linear movement. If a leadscrew is binding, the motor turns but the gantry doesn't move until enough force builds up, then it jumps. Result: the algorithm overcorrects repeatedly. Disconnect each Z leadscrew and verify it rotates freely through its full range. Lubricate with PTFE grease if needed.

One Corner Always Reads High

If the same corner consistently measures higher, check for: debris under the bed, a warped bed carrier, or a Z belt that's too tight on that corner (V2.4). On Trident, swap the probe point order — if the problem moves, it's a probe repeatability issue, not a mechanical one.

QGL Fails with "Max adjust exceeded"

Your gantry is too far out of level for the max_adjust limit. Temporarily increase max_adjust: 5, run QGL, then mechanically tram the gantry closer and reset max_adjust to 2. This is safer than leaving max_adjust high — a large sudden adjustment can bind the Z belts.

Integrating with PRINT_START

For fully automatic operation, integrate Z tilt/QGL into your PRINT_START macro with proper conditional logic:

[gcode_macro PRINT_START]
gcode:
  {% set BED_TEMP = params.BED_TEMP|default(105) %}
  {% set EXTRUDER_TEMP = params.EXTRUDER_TEMP|default(245) %}

  # Heat bed to target
  M140 S{BED_TEMP}
  M106 S255
  G28

  # Soak bed for thermal stability
  M190 S{BED_TEMP}
  G4 P600000

  # Gantry leveling
  {% if printer.toolhead.homed_axes != "xyz" %}
    G28
  {% endif %}

  # Conditional: use Z_TILT on Trident, QGL on V2.4
  {% if printer.configfile.config.quad_gantry_level is defined %}
    QUAD_GANTRY_LEVEL
  {% elif printer.configfile.config.z_tilt is defined %}
    Z_TILT_ADJUST
  {% endif %}

  BED_MESH_CALIBRATE
  M109 S{EXTRUDER_TEMP}
  G28 Z
  G1 Z5 F300

Conclusion

Proper gantry leveling separates a good Voron from a great one. Understand whether you need Z_TILT_ADJUST or QUAD_GANTRY_LEVEL, configure your probe correctly, soak the bed before calibrating, and keep mechanical components clean and lubricated. With these procedures in place, your first layer will be consistent across the entire bed, every single time.