Set the belt tension so it is firm but not tight. Too loose skips, too tight wears the bearings.
What the message means
The belt meshes with the pulley teeth. A loose belt rides up over the teeth under load, and a misaligned pulley pushes it sideways.
Fix it in this order
- Tension the belt until it twangs lightly and does not sag.
- Check the pulleys sit in the same plane, with a straightedge.
- Use a pulley of at least 16 teeth where you can, since small ones wear the belt faster.
- Check the grub screw is tight on the flat of the shaft.
- Keep oil and dust off the belt.
- Check the motor current is not so high that the belt is overloaded.
Why it happens
A belt skips teeth when it is too loose, when the pulley is not fixed to the shaft, or when the motor torque and acceleration are too high. A belt that is too tight wears the bearings.
Tension the belt so it twangs without feeling stretched, tighten the grub screw on the pulley flat of the shaft, check the pulley and the belt are both GT2, and reduce acceleration.
If you see this, do this
| You see | Do this |
|---|---|
| Skips under load | Tension or overloaded. |
| Belt walks sideways | Alignment or flange. |
Related
stepper loses steps, part slips on the shaft.
Last reviewed: November 2026. These are the usual causes and the order that finds them fastest. Test on your own board; clones and cables differ.
Why this happens
A GT2 belt has teeth every 2 mm. It drives the load by the teeth meshing with the pulley. Under force, a loose belt rides up and jumps one tooth at a time; each jump moves the carriage 2 mm out of step with the motor, and the controller never knows. The same happens if the pulley slips on the shaft or the motor misses steps.
Pulley size matters. A 20-tooth GT2 pulley has a pitch diameter of 20 x 2 / pi = 12.73 mm and moves the belt 40 mm per turn. Fewer teeth mean fewer teeth in mesh and more wear. Too much tension does the opposite harm: it loads the motor and idler bearings.
How to confirm the cause
- Mark the carriage and the frame. Move out and back ten times and look at the mark. A shift that grows each time shows lost steps or skipped teeth.
- Divide the shift by 2 mm. A shift of 4 mm after ten trips is about two teeth.
- Hold the belt with a finger and turn the pulley by hand. Look for the pulley turning while the belt does not.
- Look at the belt teeth. Shiny, worn or frayed teeth mean wear from a loose belt or a misaligned pulley.
- Place a straightedge across both pulleys. A gap shows misalignment.
Worked example
A repeatability test in G-code, plus the steps-per-mm calculation for a 20-tooth pulley and a 200-step motor at 16 microsteps.
G28 X
G1 X150 F3000
G1 X10 F3000
; repeat the two moves above ten times, then measure
; how far the carriage is from its home mark
; shift / 2 mm = teeth skipped
steps/mm = (200 * 16) / (20 * 2) = 3200 / 40 = 80Common mistakes
- Tightening the belt very hard to cure skipping.
- Fixing the grub screw on the round part of the shaft instead of the flat.
- Mixing belts and pulleys of different pitch. GT2 is 2 mm; other types are not compatible.
- Using high acceleration and ignoring the motor’s torque limit.
- Using a pulley with the wrong bore, so it wobbles.
If this did not fix it
- Stepper driver current set too low or the driver overheating and cutting out.
- Rails or bearings binding, so the load is higher than expected.
- A belt clamp slipping at the carriage rather than skipping at the pulley.