Klipper 3D Printing File Coordinate Exception
A coordinate exception in Klipper is not a crash. It is the firmware refusing to move a toolhead to a position it cannot justify. This page explains where the limits come from, which ones you can change, and which ones point at a mechanical or wiring fault. Written for engineers who read klippy.log instead of guessing.
In this article
- 1
- 2
- 3
- 4
- 5
- 6
- 7
Why a Klipper 3D printing file coordinate exception starts with position limits
Klipper tracks two coordinate systems at the same time. The g-code file carries toolhead coordinates, and the kinematic solver converts them into stepper positions. When the two disagree, the firmware raises an exception instead of moving. That is the whole mechanism behind most coordinate faults.
Position limits are defined in printer.cfg under [stepper_x], [stepper_y] and [stepper_z]. The values position_min and position_max are not suggestions. They are hard boundaries. A move that asks for X = 305 on a bed declared 0 to 300 is rejected before any motor turns.
The exception message usually names the axis and the requested value. Read it literally. If the file says X 305 and the config says 300, the problem is in the slicer profile, not in the firmware. The printer is reporting a real mismatch, not a random glitch.
One trap: a bed mesh or probe offset can push a valid-looking move outside the limit. If a 300 mm file prints fine without a mesh but throws an exception with one, check the mesh margins before editing the model.
- 1Read the axis nameThe exception tells you which limit was crossed. Start there.
- 2Compare unitsA slicer set to inches will send coordinates 25.4 times too large.
- 3Check the meshProbe offsets and mesh margins shift the usable envelope.
- 4Do not widen limits blindlyA limit that is too generous hides a mechanical fault.
When the fault is kinematic rather than numeric
On a CoreXY or delta machine, the firmware does not move X and Y motors directly. It moves two belts or three towers, and solves the geometry. A coordinate exception on these machines can come from the solver, not from the file.
Delta printers are the clearest case. The printable radius, arm length and tower spacing define a working envelope. Near the edge, the required arm angle can exceed what the linkage can physically reach. Klipper rejects the move because the math has no real solution.
CoreXY adds another failure mode. If the two belts are not tensioned equally, one carriage lags. The commanded position and the actual position drift apart, and the error accumulates over thousands of moves. The firmware may not throw an exception at all until the drift crosses a limit.
A quick diagnostic: jog each axis by hand with motors disabled. Any rough spot, tight point or audible click is a mechanical cause. Fix that before touching the config.
GPIO pin mapping and signal conflicts on single-board hosts
Single-board computers used as Klipper hosts expose GPIO pins that are shared with other functions. A pin declared for a fan PWM output may also be used by the audio or HDMI subsystem. Two drivers on one pin produce erratic step signals.
The symptom is specific. The axis moves, but the position is wrong, or the move stalls partway and the firmware reports a coordinate mismatch. It often appears only at certain speeds, which makes it look random.
Check the pin declaration in printer.cfg against the board's pinout document. Confirm the pin is not reserved by the operating system. On some boards, a default pull-up on a pin will hold a signal high when the driver expects it low.
Optical isolation on the expansion board helps here. It separates motor drive signals from the host GPIO, so switching noise from the stepper drivers cannot feed back into the host. This matters most on machines with long ribbon cables.
Motor current, microstepping and accumulated position error
A stepper that loses steps does not report it. Klipper assumes the commanded position was reached. The error therefore accumulates silently until a later move crosses a limit and triggers an exception far from the original fault.
Two settings drive most step loss. Run current too low and the motor stalls under load. Run current too high and the driver or motor overheats, which changes the torque curve. Both produce the same visible result.
Microstepping affects torque per step. Running 256 microsteps looks smooth, but torque per microstep is small. A machine with high belt friction may do better at 32 or 64 microsteps with higher current.
Mechanical resistance is the other half. Dry linear rails, overtightened belts and misaligned lead screws all raise the load. Set the current to suit the mechanics, not the other way around.
- 1Check driver temperatureA hot driver is a current setting that is too high.
- 2Reduce microsteps32 or 64 often holds position better than 256 under load.
- 3Move each axis by handResistance you can feel will cause step loss at speed.
G-code, slicer profiles and coordinate origin mismatches
Not every exception comes from hardware. Slicers write a coordinate origin into the file. If the slicer assumes a bed origin at the front-left corner and the printer config uses center origin, every move is offset.
The offset is usually the bed half-width. A 300 mm bed with a mismatched origin produces a 150 mm shift. That is large enough to trigger a limit on the first layer.
Watch for absolute and relative positioning modes. G90 sets absolute, G91 sets relative. A file that switches modes without a clear return to absolute will send moves relative to the last position, and the error grows with each layer.
Also check for a start macro that homes to a different corner than the slicer expects. Vendors often ship a homing macro and a slicer profile that were tuned for different bed sizes.
How to confirm the fix before running a full print
Do not test a coordinate fix with a 12-hour print. Write a short verification file that exercises the full travel envelope at a slow feed rate. Fifty moves are enough to expose a limit error.
Log the commanded and reported position for each move. Klipper exposes toolhead position through the API. A small script can compare the two and flag any drift beyond the expected tolerance.
Run the same file three times. A fault that appears once in three runs is usually mechanical or thermal, not a config error. A fault that appears every run is a config error.
Once the file passes, print a single-layer test part that reaches all four corners. Measure the actual part against the CAD model. The difference tells you whether the fix corrected position or just moved the limit.
Coordinate exception symptoms and their likely causes
| Symptom | Likely cause | First check | Fix direction |
|---|---|---|---|
| Exception names X or Y limit | File exceeds position_max | Slicer bed size vs config | Correct slicer profile |
| Only fails near bed edge | Delta reach or mesh margin | Printable radius vs mesh | Shrink mesh or build area |
| Position drifts over layers | Belt tension or step loss | Belt tension, driver current | Retension and reset current |
| Fails at one speed only | GPIO pin conflict | Pinout vs printer.cfg | Reassign pin, add isolation |
| Every move offset by half bed | Origin mismatch | Slicer origin vs config | Match origin in both |
| Random stalls on long moves | Driver overheat | Driver temperature | Lower run current |
| Exception only with mesh on | Probe offset sign | Z offset sign and value | Flip or retune offset |
Fix the cause, not the limit
If the exception names a limit and the mechanics are sound, correct the slicer profile or mesh margin. If the mechanics show resistance, step loss or a hot driver, fix the hardware first and leave the limits alone. Widening position_max to silence an exception hides a fault that will return as a scrapped part.
Common questions about Klipper coordinate exceptions
Can I just increase position_max to clear the exception?
You can, and the exception will stop. But position_max describes the physical travel of the machine. Setting it beyond that makes the firmware command moves the hardware cannot complete.
The usual result is a belt skip or a carriage hitting a hard stop. Correct the file or the mesh margin instead.
Why does the exception only appear on some files?
Because the fault is tied to a specific move, not to the machine. A file that stays inside the envelope will never trigger it.
Check the bounding box of the model in the slicer. If the exception appears when the model is near the edge, the cause is geometric.
Is a coordinate exception ever a firmware bug?
Rarely. The limit and kinematic checks are deterministic math. The same input produces the same result every time.
If the same file throws an exception on one machine and not another, compare the two printer.cfg files before assuming a firmware fault.
How do I tell step loss from a config error?
Run the same job twice and measure the finished part. A config error produces the same offset both times. Step loss produces a different offset each run.
Step loss also tends to grow with print height, because the error accumulates.
Does microstepping affect coordinate accuracy?
It affects torque per step, not the commanded position. Klipper calculates position from step counts regardless of microstep setting.
But if a high microstep setting causes torque loss and skipped steps, the reported position will diverge from the real one.
When should I stop debugging and machine the part instead?
When the geometry is functional rather than aesthetic, or when the printer cannot hold the tolerance the part needs. FDM typically holds ±0.2 mm on a good day.
For a bracket, a housing or a fixture with a fit requirement, CNC machining gives ±0.005 mm and a documented inspection report.
Send us the part that keeps failing to print
Upload the STEP file and we will return a quotation and a free DFM analysis within 12 hours. No minimum order quantity, from one prototype to 10,000+ parts.
12-hour quote±0.005 mm tolerance100% inspection
More from GreatLight
We publish setup notes, tooling trials and inspection data from the factory floor.
