Common Error Overview

This page is for quickly locating common Klipper errors. First, find the complete error keyword in klippy.log, then proceed to the corresponding category page for resolution.

Quick Index

Error Type	Common Keywords	Troubleshooting Entry Point
Connection Issues	Unable to connect, Invalid CAN uuid, Lost communication, MCU Protocol error, /dev/serial/by-id	This page Connection Issues, MCU ID Config, CAN Network & ID Search
Configuration Issues	not valid, not a valid config section, must be specified, Unable to parse, SAVE_CONFIG, Option conflict	Configuration Errors
Macro & Slicer Commands	Unknown command, Error evaluating 'gcode_macro, jinja2.exceptions.UndefinedError, dict object has no attribute	Configuration Errors
Motion & Homing	Move out of range, Must home axis first, No trigger, Endstop still triggered	Motion, Endstop & Leveling Errors
G-code Parsing	Unable to parse move, Invalid speed, Machine does not support G20, G2/G3	Motion, Endstop & Leveling Errors, Arc Fitting Guide
Probe Leveling	Probe triggered, No trigger on probe, samples_tolerance, bed_mesh, BLTouch failed, Z_TILT, QUAD_GANTRY_LEVEL	Motion, Endstop & Leveling Errors
Temperature & Heating	ADC out of range, not heating at expected rate, Verify heater, temperature	Temperature, Heating & Extrusion Errors
Extrusion Issues	Extrude below minimum temp, Extrude only move too long, Move exceeds maximum extrusion, Filament sensor, M600	Temperature, Heating & Extrusion Errors
Performance Timeouts	Timer too close, Missed scheduling, Stepper too far in past, Rescheduled timer, restarting too fast, SD busy	System, Performance & Service Errors
TMC Drivers	Unable to read tmc uart, Unable to write tmc spi, GSTAT, coil short circuit	TMC Error Troubleshooting
CAN Network	bytes_invalid, Network is down, No buffer space available, Invalid CAN uuid	CAN Network & ID Search
Sensor Peripherals	Invalid adxl345 id, No data, Insufficient axis, Eddy current sensor error, Invalid read data	Accelerometer Testing & Calibration, EDDY Issues Collection

Related Configuration Page Quick Reference

Error Direction	Recommended Reference
Configuration Syntax, Indentation, Comments, Duplicate Pins	Configuration Modification Guide
Homing Direction, Axis Direction, Force Move	Homing & Direction Calibration Guide
Endstops, TAP, Optical Endstops, Proximity Switches	Endstops Related
Endstopless Homing, Virtual Endstop Sensitivity	Endstopless Usage
Heating, PID, Slow Heating, Temperature Protection	Heating Related, verify_heater Optimization, M109 Optimization
Fan Configuration, Driver Fans, 7040 Fans	Fan Reference Configuration
Extruder Parameters, Rotation Distance, Extruder Config	Extruder Reference Configuration, Machine Calibration
Start/End Macros, Pause/Resume, Leveling & Bed Mesh Macros	Macros Introduction
Common Debug Commands, Probe, Resonance Compensation	Common Debug Directives

Connection Issues

MCU ID Configuration Description

The MCU ID in Klipper refers to the identification information used in the [mcu] or [mcu xxx] configuration section for connecting to the control board. Different communication methods have different formats:

Connection Method	Configuration Item	Example
USB Firmware	serial:	serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx
CAN Firmware	canbus_uuid:	canbus_uuid: xxxxxxxxxxxx
Host MCU	serial:	serial: /tmp/klipper_host_mcu

Filling Rules:

1. The mainboard defaults to using [mcu], while tool boards or expansion boards use custom names like [mcu tool], [mcu toolboard], etc.
2. USB firmware only fills in serial:, and CAN firmware only fills in canbus_uuid:; do not retain both items in the same [mcu].
3. In multi-MCU machines, each [mcu xxx] must use its own real ID; do not copy the same USB ID or CAN UUID.
4. The name of [mcu xxx] affects the pin prefix; for example, a pin for [mcu tool] should be written as tool:gpio13; keep the name case consistent.
5. The xxxxxxxx in documentation examples cannot be used directly; it must be replaced with the actual searched ID.

Common Errors:

• Using a flashing mode ID (such as an ID containing katapult or canboot) as a Klipper firmware ID.
• Configuring canbus_uuid: in USB firmware, or retaining the old serial: in CAN firmware.
• Configuring a tool board as [mcu], overwriting the mainboard MCU configuration.
• Pin prefix inconsistency with the MCU name, for example, configuring [mcu toolboard] but writing the pin as tool:gpio13.

USB ID Query: For USB firmware, run ls /dev/serial/by-id/* to obtain the ID.

CAN ID Query: CAN Network and ID Search

Tool Board Configuration: Tool Board MCU Addition and Cross-Board Configuration

mcu 'xxx': Unable to connect

Error Message: The host cannot find or connect to the mainboard.

Loading...

Common Causes:

• The USB device ID is not filled in or is incorrect.
• The CAN UUID is not filled in, is incorrect, or the device is offline.
• UTOC, USB cable, CAN bridge firmware, or power supply is abnormal.
• CAN0 is not started, or the CAN network configuration is abnormal.

Resolution Steps:

1. Open klippy.log and scroll to the bottom to confirm the specific error information.

2. If [Errno 2] appears, it usually means the found USB device ID has not been added to printer.cfg.

   Loading...

3. If Serial connection closed appears, you usually need to re-search the CAN ID and check the CAN network.

   Loading...

4. If Unable to open CAN port: [Errno 19] No such device appears, it usually means a missing UTOC device, USB-to-CAN firmware, or CAN0 device.

   Loading...

5. If [Errno 100] Network is down or [Errno 105] No buffer space available appears, please re-check the CAN0 configuration according to CAN Network & ID Search.

mcu 'mcu': Invalid CAN uuid

Error Message: The CAN UUID is invalid or unrecognizable.

Loading...

Cause: canbus_uuid: is filled in incorrectly, the device is offline, or the CAN network is not communicating properly.

Resolution:

1. Re-search the CAN UUID according to CAN Network & ID Search.
2. Confirm that printer.cfg contains the UUID actually found.
3. Ensure serial: and canbus_uuid: are not both enabled in the same [mcu] section.
4. Check CAN-H, CAN-L, termination resistors, power supply, and firmware CAN rate.

Option 'serial' in section 'mcu' must be specified

Error Message: The serial option must be specified in the [mcu] config section.

Loading...

Cause: serial: was not filled in when connecting via USB firmware, or the [mcu] config section was accidentally deleted.

Resolution:

1. Re-search for the USB device ID.
2. Fill in the [mcu] section of printer.cfg:

[mcu]
serial: /dev/serial/by-id/ACTUALLY_FOUND_ID

3. Save and restart Klipper.

If the current mainboard is flashed with CAN firmware, use canbus_uuid: instead of serial:.

USB ID Not Found / System Service Interference

Error Message: ls /dev/serial/by-id/* produces no output or returns No such file or directory; Klipper reports mcu 'xxx': Unable to open serial port, [Errno 2] No such file or directory during connection, or the USB mainboard repeatedly disconnects and reconnects in the system.

Common Causes:

• The mainboard is not running the Klipper firmware but is in a flashing mode (Katapult / CanBoot / DFU, etc.).
• Issues with USB cable, USB port, host power supply, or mainboard power supply.
• Some udev versions on Debian 11 Bullseye may not generate the /dev/serial/by-id/ device path.
• Desktop Linux may have ModemManager or BRLtty installed, which can hijack serial ports, preventing Klipper from connecting stably to the mainboard.

Troubleshooting Methods:

Power Off Operation

Before re-plugging USB cables, checking mainboard power cables, or organizing USB/CAN wiring, completely turn off the printer and disconnect the power supply. Do not touch interface wiring or terminals while powered on.

1. First, confirm the mainboard is flashed with and running Klipper firmware. The USB ID should contain usb-Klipper. Do not write katapult, canboot, Bootloader, or DFU mode IDs into printer.cfg.
2. Power off, then replace the USB data cable and host USB interface with reliable ones. Re-power and execute ls /dev/serial/by-id/* again.
3. If using Debian 11 Bullseye, older MainsailOS / FluiddPi / Armbian, etc., check the udev version:

apt-cache policy udev

4. If confirmed as a Debian 11 udev issue, prioritize updating udev through the system's normal update sources, or switch to a newer system image.
5. Check for services that might hijack serial ports:

systemctl list-units --all | grep -Ei 'ModemManager|brltty'

6. If these services are installed and your host does not require modem or braille terminal functionality, replace the full unit name from the previous command into the command below, stop, disable, and reboot:

sudo systemctl disable --now ModemManager.service
sudo systemctl disable --now brltty.service
sudo systemctl disable --now brltty.path

7. Afterwards, re-query the USB ID and confirm serial: under [mcu] in printer.cfg matches the actual output.

Related Configuration Reference: MCU ID Config.

Lost communication with MCU

Error Message: Klipper loses communication with the MCU. The log may show Lost communication with MCU, Lost communication with mcu, or similar prompts.

Common Scenarios: During homing or movement, the mainboard or toolhead board goes offline as soon as an endstop is triggered; it reconnects after a power cycle.

Common Causes:

• Incorrect endstop wiring causing signal pin shorting to power or ground upon trigger.
• Incorrect order of power, ground, and signal wires when using three-wire endstops, optical endstops, or hall effect endstops.
• Damaged wire insulation on endstop cables, pinched wires, or short circuits during cable chain movement.
• Triggering the endstop causes a voltage drop on the mainboard, leading to MCU reset or USB/CAN communication interruption.
• The USB/CAN communication line between the MCU and host passes near strong interference sources, making disconnection more likely when endstops trigger or axes move.
• The endstop pin configured in printer.cfg does not match the actual wiring, triggering the wrong interface.

Troubleshooting Methods:

Power Off Operation

Before plugging/unplugging endstop cables, checking pinouts, inspecting cable chain wiring, or using a multimeter for continuity/resistance, completely turn off the printer and disconnect the power supply. Multimeter resistance/continuity mode can only be used when power is off. Do not measure resistance or perform short circuit tests while powered on.

1. Power off and check the endstop switch wiring sequence, especially whether VCC, GND, and Signal are connected correctly for three-wire endstops.
2. Power off, temporarily disconnect the endstop cable, reassemble, and test if the mainboard still drops offline when powered on.
3. Power off and use a multimeter in continuity/resistance mode to check for short circuits when the endstop is triggered, focusing on whether the signal pin is connected to power.
4. Inspect cable chains, connectors, and wiring bend points to ensure no pinched wires or short circuits occur during triggering or movement.
5. Check the USB/CAN communication line between the MCU and host, routing it away from motor wires, heater wires, heated bed wires, and power wires as much as possible.
6. If the machine chassis, power supply, or shielding is not properly grounded, it may be more susceptible to interference. Only check manufacturer-provided grounding points and outlet status; do not disassemble the power supply or modify mains wiring.
7. Confirm the endstop pin in the configuration matches the mainboard documentation and actual wiring.
8. After fixing the issue, execute QUERY_ENDSTOPS to verify the endstop status changes from open to TRIGGERED correctly.

Related Configuration Reference: Endstops Related, Power Wiring Guide.

MCU Protocol error

Error Message: MCU protocol error. The log may show MCU Protocol error, Unknown command, or Command format mismatch.

Loading...

Common Causes:

• The host-side Klipper was updated, but the mainboard or toolhead board firmware was not recompiled and re-flashed.
• Firmware version mismatch between the host-side Klipper and peripheral MCUs (mainboard, toolhead board, EDDY, ADXL, etc.).
• Using a custom system or third-party plugins causes the Klipper host to support commands that differ from the MCU.

Resolution:

1. Confirm if Klipper, the system image, or plugins were recently updated.
2. Recompile and re-flash the Klipper firmware for all MCUs.
3. If using peripheral MCUs (toolhead board, EDDY, ADXL, etc.), update the corresponding peripheral firmware simultaneously.
4. If using a custom system, verify it supports the current Klipper version.
5. After flashing, execute FIRMWARE_RESTART, then re-test the connection.

Specialized FAQs

Topic	Entry Point
Configuration Conflicts, Parameter Parsing, SAVE_CONFIG	Configuration Errors
Unknown Commands, Macro Templates, Slicer Start G-code	Configuration Errors
Motion, Homing, Endstops, Probes, Bed Mesh Leveling	Motion, Endstop & Leveling Errors
Temperature, Heating, Extrusion, Filament Runout	Temperature, Heating & Extrusion Errors
Performance, Timeouts, Firmware, System Services	System, Performance & Service Errors
G2/G3, Arc Fitting, Slicer Path Accuracy	Arc Fitting Guide
TMC Driver Communication, Overtemp, Coil Issues	TMC Error Troubleshooting
CAN Network, UUID, bytes_invalid	CAN Network & ID Search
Accelerometer & Resonance Testing	Accelerometer Testing & Calibration
EDDY Eddy Current Probe	EDDY Issues Collection