GUIDE

Klipper Bed Mesh: Why You Need It and How to Set It Up

Difficulty Beginner
Time Required ⏱ 25 minutes
Tools 2 required
Before You Start
Tools
  • Klipper console (Mainsail or Fluidd)
  • Probe installed and configured (TAP, Klicky, CR Touch, etc.)

A bed that's 0.2mm higher in the back-right corner than the front-left will cause the first layer to fail somewhere, regardless of how perfectly you calibrated your Z offset. Bed mesh solves this by mapping the entire surface and dynamically adjusting the Z height throughout every print. It's not optional on a printer larger than 200mm.

Why No Bed Is Flat

Every print bed has some variation across its surface. The causes are structural and thermal:

Manufacturing tolerance: Even high-quality borosilicate glass and precision-ground aluminum tooling plates have surface variation measured in hundredths of a millimeter. Spring steel PEI sheets add their own variation depending on how evenly they’re attached to the magnetic base.

Thermal expansion: Aluminum expands approximately 23 micrometers per meter per degree Celsius. A 300mm aluminum bed heating from 20°C to 100°C expands ~1.6mm across its length. But it doesn’t expand uniformly. The center heats faster than the edges, causing the bed to bow convex (center rises) or concave (edges rise) depending on the heater distribution and bed material.

Frame compliance: On CoreXY printers like the Voron 2.4, the bed is fixed, but the frame itself can flex slightly under thermal load. The Z rails, gantry, and frame extrusions all have some compliance.

The net effect is that your bed surface is a landscape, not a plane. Bed mesh maps that landscape with a probe and lets Klipper ride it throughout the print.

Prerequisites

Before setting up bed mesh, your printer needs:

  1. A working probe — TAP, Klicky, Voron TAP, CR Touch, BLTouch, or any probe that Klipper supports. The probe must be calibrated (its Z offset set correctly via PROBE_CALIBRATE).
  2. A calibrated Z offset — bed mesh compensation is applied on top of your base Z offset. If your Z offset is wrong, the mesh makes it consistently wrong across the whole bed.
  3. Bed at print temperature — always calibrate with the bed heated. A cold mesh is inaccurate at print temperature due to thermal expansion.
Warning: Do not run BED_MESH_CALIBRATE without first completing PROBE_CALIBRATE and setting your Z offset. The mesh is a correction relative to your base Z offset, not a replacement for it.

Configuration in printer.cfg

Add the following section to your printer.cfg:

[bed_mesh]
speed: 120
horizontal_move_z: 5
mesh_min: 30, 30
mesh_max: 270, 270
probe_count: 5, 5
mesh_pps: 2, 2
algorithm: bicubic
bicubic_tension: 0.2

Key parameters explained:

ParameterWhat it does
mesh_minFirst probe point, bottom-left (must clear probe offsets from bed edge)
mesh_maxLast probe point, top-right (must clear probe offsets from bed edge)
probe_countGrid size — 5, 5 probes 25 points in a 5×5 grid
algorithmlagrange for ≤6×6 grids, bicubic for larger grids
bicubic_tensionHigher values follow surface variation more closely (0.2 is a good default)

Setting mesh_min and mesh_max: These must be inset from your bed edges by at least the probe’s XY offset from the nozzle. If your probe is 25mm to the right of the nozzle (x_offset: 25), then mesh_min X must be at least 25mm from the bed’s left edge to ensure the probe can reach that point without the nozzle going off-bed.

Choosing probe_count: More points give a more accurate mesh at the cost of calibration time.

  • 3, 3 (9 points) — fast, adequate for very flat beds
  • 5, 5 (25 points) — good balance, recommended for most builds
  • 7, 7 (49 points) — thorough, recommended for 300mm+ beds with known warping

Running BED_MESH_CALIBRATE

With the configuration in place and the bed at printing temperature, home your printer and run the calibration:

G28
BED_MESH_CALIBRATE

The probe will move to each grid point in sequence, probe the surface, and build a height map. On a 5×5 grid at 120mm/s probe speed, this takes about 3–5 minutes.

When complete, view the mesh in Mainsail or Fluidd’s bed mesh visualization. A healthy mesh shows gradual variation with no sharp spikes. What you’re looking for:

  • Total variation under 0.5mm: Normal for most quality beds at print temperature. The mesh will handle this easily.
  • Total variation 0.5–1.5mm: The mesh will compensate, but you might want to check that your bed is properly seated and that your Z leveling screws are adjusted to minimize coarse tilt.
  • Total variation over 2mm or sharp peaks: This usually indicates a hardware problem: a screw protruding through the bed, a warp from thermal damage, or an incorrect probe trigger. Investigate before printing.
Tip: If the visualization shows a consistent tilt across the whole bed (high on one side, low on the other), use your Z leveling screws to correct the coarse tilt first, then re-run BED_MESH_CALIBRATE. The mesh is better at handling complex warps than simple tilts.

Saving and Applying the Mesh

After calibration, save the mesh to a named profile:

BED_MESH_PROFILE SAVE=default
SAVE_CONFIG

To apply this mesh automatically on every print, add the following to your print start macro (in your printer.cfg or slicer start G-code):

[gcode_macro PRINT_START]
gcode:
    G28                              # home all axes
    BED_MESH_CALIBRATE               # probe fresh mesh
    BED_MESH_PROFILE LOAD=default    # or load saved profile
    G1 Z5 F3000
    G1 X5 Y5 F6000
    # ... rest of your start routine

For printers where bed mesh rarely changes (a fixed, rigid bed at consistent temperatures), loading a saved profile is faster than recalibrating every print. For printers with significant thermal variation between prints, calibrating fresh each time is more accurate.

Checking the Mesh is Active

To verify the mesh is loaded and active, run:

BED_MESH_OUTPUT

This prints the current mesh matrix to the console. If it shows all zeros, no mesh is loaded — run BED_MESH_PROFILE LOAD=default to activate your saved profile.

You can also check the live visualization in Mainsail under the “Heightmap” tab, which shows the active mesh overlaid on a 3D representation of your bed surface.

Note: Bed mesh compensation is only applied to Z movements. It does not affect XY accuracy. If your first layer has XY-plane issues — gaps between lines, inconsistent width — those are extrusion or flow rate problems, not mesh problems.