Common Error Overview

This page is used to quickly locate common Klipper errors. Please first find the complete error keywords in klippy.log, then go to the corresponding category page for resolution.

Quick Index

Error Type	Common Keywords	Troubleshooting Entry
Connection Issues	Unable to connect, Timeout on connect, Wait for identify_response, Serial connection closed, Invalid CAN uuid, Lost communication, MCU Protocol error, /dev/serial/by-id, Unable to issue reset command, Got EOF when reading from device	Connection issues on this page, MCU ID Configuration, CAN Network and ID Search
Configuration Issues	not valid, not a valid config section, must be specified, Unable to parse, SAVE_CONFIG, Option conflict, virtual_sdcard, pause_resume, display_status	Configuration Errors
Macro and Slicer Commands	Unknown command, Error evaluating 'gcode_macro, jinja2.exceptions.UndefinedError, dict object has no attribute	Configuration Errors
Motion and Homing	Move out of range, Must home axis first, No trigger, Endstop still triggered, virtual_endstop, Unknown pin chip name, Homing failed due to printer shutdown	Motion, Endstop and Leveling Errors, Sensorless Homing Troubleshooting
G-code Parsing	Unable to parse move, Invalid speed, Machine does not support G20, G2/G3	Motion, Endstop and Leveling Errors, Arc Fitting Recommendations
Probe Leveling	Probe triggered, No trigger on probe, samples_tolerance, bed_mesh, BLTouch failed, Z_TILT, QUAD_GANTRY_LEVEL, no samples between time, SVD did not converge	Motion, Endstop and Leveling Errors, BLTouch Configuration and Troubleshooting
Temperature and Heating	ADC out of range, not heating at expected rate, Verify heater, temperature, Thermocouple reader fault	Temperature, Heating and Extrusion Errors
Extrusion Issues	Extrude below minimum temp, Extrude only move too long, Move exceeds maximum extrusion, Filament sensor, M600	Temperature, Heating and Extrusion Errors
Performance Timeouts	Timer too close, Missed scheduling, Stepper too far in past, Move queue overflow, stepcompress, Rescheduled timer, restarting too fast, SD busy, Unhandled exception during run, hard pwm event, Can't reset time when stepper active	System, Performance and Service Errors
TMC Drivers	Unable to read tmc uart, Unable to write tmc spi, GSTAT, coil short circuit, tmcuart_response	TMC Error Troubleshooting
CAN Network	bytes_invalid, Network is down, No buffer space available, Invalid CAN uuid, USB CANBUS bridge, BUS-OFF	CAN Network and ID Search, CAN Error Troubleshooting
Sensor Peripherals	Invalid adxl345 id, No data, Insufficient axis, Eddy current sensor error, Invalid read data, load_cell_probe, START_READ_NACK, I2C, BUS_TIMEOUT	Accelerometer Testing and Calibration, EDDY Issue Compilation, Load Cell Probe Troubleshooting, I2C Communication Errors on this page
Resonance Compensation and Pressure Advance	shaper_freq, input_shaper, pressure_advance, smooth_time, accel_chip, TEST_RESONANCES, SHAPER_CALIBRATE	Resonance Compensation and Pressure Advance

Related Configuration Page Quick Reference

Error Direction	Recommended Reference
Configuration syntax, indentation, comments, duplicate pins	Configuration Modification Instructions
Homing direction, axis direction, forced movement	Homing and Direction Calibration Guide
Endstops, TAP, optical endstops, proximity switches	Endstop Related
Sensorless homing, virtual endstop sensitivity	Sensorless Usage
Heating, PID, slow heating, temperature protection	Heating Related, verify_heater Optimization, M109 Optimization
Fan configuration, driven fans, 7040 fans	Fan Reference Configuration
Extruder parameters, rotation distance, extrusion configuration	Extruder Reference Configuration, Machine Calibration
Start/end macros, pause/resume, leveling and bed mesh macros	Macro Introduction
Common debugging commands, probes, resonance compensation	Common Debugging Directives

Connection Issues

MCU ID Configuration Description

In Klipper, the MCU ID refers to the identification information used to connect to the control board within the [mcu] or [mcu xxx] configuration sections. Different communication methods require different syntax:

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

Filling Rules:

1. The mainboard uses [mcu] by default, while tool boards or expansion boards use custom names such as [mcu tool] or [mcu toolboard].
2. For USB firmware, only fill in serial:; for CAN firmware, only fill in canbus_uuid:; do not include both items in the same [mcu] section.
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, pins for [mcu tool] should be written as tool:gpio13; the case of the name must remain consistent.
5. The xxxxxxxx in the documentation examples cannot be used directly and must be replaced with the actual ID found.
6. For RS232 devices, in addition to serial:, baud: 250000 and restart_method: command are usually also required; refer to the corresponding product documentation.

Common Mistakes:

• Using a flashing mode ID (such as an ID containing katapult or canboot) as the Klipper firmware ID.
• Configuring canbus_uuid: for USB firmware, or retaining the old serial: for CAN firmware.
• For RS232 devices, only filling in the path and omitting the required baud: or restart_method:.
• Configuring the tool board as [mcu], thereby overriding the mainboard MCU configuration.
• The pin prefix does not match the MCU name, for example, the configuration is [mcu toolboard] but the pin is written as tool:gpio13.

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

CAN ID Query: CAN Network and ID Search

RS232 Path Query: Execute ls -l /dev/serial/by-path/ to obtain a stable device path.

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 main board.

Loading...

Common Causes:

• USB device ID is not filled in or is filled in incorrectly.
• CAN UUID is not filled in, is filled in incorrectly, 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.

Troubleshooting Steps:

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

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

   Loading...

3. If Timeout on connect, Wait for identify_response, or Serial connection closed appears, continue troubleshooting according to MCU Connection Handshake Timeout; this can occur with both USB connections and serial bridge connections.

   Loading...

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

   Loading...

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

mcu 'mcu': Invalid CAN uuid

Error Message: The CAN UUID is invalid or cannot be recognized.

Loading...

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

Solution:

1. Re-search for the CAN UUID according to CAN Network and ID Search.
2. Confirm that the UUID filled in printer.cfg matches the one actually discovered.
3. Confirm that both serial: and canbus_uuid: are not enabled simultaneously in the same [mcu] section.
4. Check CAN-H, CAN-L, termination resistors, power supply, and firmware CAN speed.

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

Error Message: serial must be specified in the [mcu] configuration section.

Loading...

Cause: serial: was not filled in for a USB firmware connection, or the [mcu] configuration section was accidentally deleted.

Solution:

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

[mcu]
serial: /dev/serial/by-id/actual-discovered-ID

3. Save and restart Klipper.

If the main board is currently flashed with CAN firmware, use canbus_uuid: instead of serial:.

USB ID Not Found / System Service Interference

Error Message: Executing ls /dev/serial/by-id/* produces no output or reports 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 main board repeatedly disconnects and reconnects in the system.

Common Causes:

• The main board is not running the Klipper firmware and is still in Katapult / CanBoot / DFU or other flashing modes.
• The USB cable, USB port, host power supply, or main board power supply is abnormal.
• Some udev versions in Debian 11 Bullseye may have issues and may not generate the /dev/serial/by-id/ device path.
• Desktop Linux may have ModemManager or BRLtty installed; these services may seize the serial device, preventing Klipper from connecting stably to the main board.

Troubleshooting Steps:

Power Off Required

Before re-plugging the USB cable, checking the main board power wiring, or organizing the USB / CAN cable harness, fully power off the printer and disconnect the power supply. Do not organize connector wiring or touch terminals while powered on.

1. First confirm that the main board has been flashed with and is running the 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, replace with a reliable USB data cable and host USB port, then power on again and re-run ls /dev/serial/by-id/*.
3. If using Debian 11 Bullseye, older MainsailOS / FluiddPi / Armbian, or similar systems, run the following command to check the udev version:

apt-cache policy udev

4. If confirmed to be a Debian 11 udev issue, preferably upgrade udev through the system's normal update sources, or switch to a newer system image.
5. Check for services that may seize the serial port:

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

6. If these services are confirmed to be installed and the host does not require modem or braille terminal functions, replace the full unit names shown in the previous command and stop and disable them, then reboot the system:

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

7. After completing the above, re-query the USB ID and confirm that the serial: setting in the [mcu] section of printer.cfg matches the actual output.

Related configuration reference: MCU ID Configuration.

Serial connection closed / Timeout on connect / Wait for identify_response

Error Message: When Klipper starts or executes FIRMWARE_RESTART, the log shows the following messages sequentially or repeatedly:

mcu 'xxx': Timeout on connect
mcu 'xxx': Wait for identify_response
serialhdl.error: mcu 'xxx': Serial connection closed

Nature of the Error: This set of errors indicates that the host has attempted to establish a connection with the MCU, but the MCU did not return firmware identification information within the specified time. It describes a connection handshake failure and does not directly indicate whether the issue is caused by firmware parameters, device paths, wiring, or the hardware itself.

Common Causes:

• The MCU firmware's communication interface, pins, clock, boot address, or bootloader offset is selected incorrectly.
• The firmware was not flashed correctly, or the main board is still in DFU, Bootloader, Katapult / CanBoot, or other flashing modes.
• serial: uses an incorrect, outdated, or incomplete device path.
• The USB data cable, USB port, serial bridge chip, or main board power supply is abnormal.
• When using a CAN tool board, the bridge device, CAN network, or canbus_uuid: configuration is abnormal.

Troubleshooting Steps:

1. Review the full klippy.log to confirm whether this set of errors occurs during the initial startup connection phase or when the MCU reconnects after dropping offline during printing.
2. Run the following commands to confirm that the system can stably recognize the MCU, and fully compare the output with the serial: setting in [mcu]:

ls -l /dev/serial/by-id/
dmesg --ctime | tail -n 80

3. If the USB ID exists and is stable, but Wait for identify_response persists, re-check the firmware compilation parameters and flashing method according to the corresponding FLY product documentation, focusing on the communication interface, bootloader offset, and clock configuration. Do not write the device ID of the flashing mode into printer.cfg.
4. If the USB ID does not exist or repeatedly disconnects in dmesg, check the system and connections according to USB ID Not Found / System Service Interference on this page.

Power Off Required

Before re-plugging or replacing the USB / CAN cable harness or checking the main board power connector, fully power off the printer and disconnect the power supply. Do not organize wiring or touch terminals while powered on.

5. After powering off, replace the cable and host interface with reliable finished products, then power on again for testing; do not disassemble the power supply or modify the mains wiring.
6. For CAN devices, continue to refer to CAN Error Troubleshooting to re-confirm the bridge device, CAN status, and UUID.
7. If the first connection is normal and only Serial connection closed occurs during printing, prioritize troubleshooting runtime disconnections according to Lost communication with MCU. Do not repeatedly reflash firmware to mask the issue.

Lost communication with MCU

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

Common Scenarios: During homing or movement, as soon as the endstop switch is triggered, the mainboard or toolboard drops offline; after power cycling, the connection is restored.

Common Causes:

• Incorrect endstop switch wiring, causing abnormal shorting of the signal pin to power or ground when triggered.
• With three-wire endstops, optical endstops, or Hall effect endstops, the power, ground, and signal wires are connected in the wrong order.
• Endstop wires have damaged insulation, are pinched, or short-circuit during cable chain movement.
• The endstop trigger causes power supply fluctuations on the mainboard, resetting the MCU or interrupting USB / CAN communication.
• The USB / CAN communication cable between the MCU and the host passes near strong interference sources, making disconnections more likely when endstops trigger or during movement.
• The endstop pins in the configuration do not match the actual wiring, triggering the wrong interface.

Troubleshooting Steps:

Power Off Before Operation

Before unplugging endstop wires, checking wire order, inspecting cable chain wiring, or using a multimeter to measure continuity/resistance, completely shut down the printer and disconnect the power supply. The multimeter resistance/continuity mode should only be used with power off. Never measure resistance or perform short-circuit tests while powered on.

1. With power off, check the endstop switch wiring order, especially whether the VCC, GND, and Signal wires of three-wire endstops are connected correctly.
2. With power off, temporarily disconnect the corresponding endstop wire, reinstall it properly, then power on to test whether the mainboard still drops offline.
3. With power off, use the multimeter continuity/resistance mode to check for shorts before and after the endstop triggers, focusing on whether the signal pin is connected to power.
4. Inspect cable chains, connectors, and wire bending points to confirm that triggering or movement will not pinch wires and cause shorts.
5. Check the USB / CAN communication cable between the MCU and host, keeping it away from motor wires, heater wires, heated bed wires, and power wires as much as possible.
6. If the machine housing, power supply, or shielding is not reliably grounded, interference may be more likely; only verify the grounding point and outlet condition provided by the manufacturer. Do not disassemble the power supply or modify the mains ground wire yourself.
7. Confirm that the endstop pins in the configuration match the mainboard documentation and actual wiring.
8. After fixing the issue, run QUERY_ENDSTOPS to confirm the endstop status changes correctly from open to TRIGGERED.

Related configuration references: Endstops, Wiring Instructions.

Unable to issue reset command on MCU

Error Message: Unable to issue reset command on MCU 'xxx', usually accompanied in the log by webhooks client ...: Disconnected and Restarting printer.

Nature of the Error: This error is generally not the first error but a follow-up prompt that appears after the MCU drops offline, loses power, or experiences communication interruption, when Klipper fails to send a reset command to the MCU. When troubleshooting, scroll up to find the first real error that occurred earlier (such as Lost communication with MCU, Timer too close, Verify heater, TMC errors, etc.).

Common Causes:

• A preceding MCU disconnection, USB / CAN communication interruption, or firmware crash prevents the reset command from being delivered.
• Insufficient power to the mainboard, toolboard, or peripheral MCU, causing power loss during the reset process.
• Poor contact or damaged USB or CAN cables.
• The MCU is forcibly reset while executing high-load tasks (such as heating or multi-point bed mesh probing).
• Strong interference between the host and MCU signals (motor wires or heater wires near communication cables).

Solutions:

Power Off Before Operation

Before reconnecting USB / CAN cables, inspecting cables, or organizing wiring, completely shut down the printer and disconnect the power supply. Do not plug or unplug cables or touch terminals while powered on.

1. Open klippy.log, find the first real error before Unable to issue reset command, and troubleshoot according to its corresponding category.
2. With power off, reconnect the USB / CAN cables, replace them with reliable finished cables, and confirm the connections are secure.
3. Check whether the mainboard and toolboard power supply is stable, avoiding unstable power circuits shared with motors or the heated bed.
4. Confirm that USB / CAN communication cables are routed away from motor wires, heater wires, and heated bed wires.
5. Execute FIRMWARE_RESTART, or if necessary, power off the entire machine for 10 seconds before powering back on.
6. If the problem persists, continue troubleshooting with reference to Lost communication with MCU and CAN Error Troubleshooting.

Got EOF when reading from device

Error Message: Got EOF when reading from device, usually appearing in the log after Attempting MCU 'xxx' reset command, indicating that the serial / USB connection has already been disconnected when the host initiates a reset on the MCU.

Nature of the Error: This is an error returned by the host operating system (Linux) layer. Klipper is merely relaying the end-of-file (EOF) character read by pyserial. It indicates that the USB / serial link has physically disconnected or the device has disappeared, rather than a configuration parameter issue.

Common Causes:

• Poor USB cable quality, poor contact, or insufficient USB port power, causing the device to drop offline during reset.
• Power fluctuations on the mainboard or toolboard, causing the MCU to reset or lose power and disappear from the system.
• Abnormal host USB controller, faulty USB port, or system USB sleep policy.
• When a CAN toolboard is bridged via USB, the bridge device drops offline (in this case, Unable to issue reset command on MCU may also appear in the log).

Solutions:

Power Off Before Operation

Before reconnecting USB / CAN cables, checking power cables, or replacing cables, completely shut down the printer and disconnect the power supply.

1. First confirm which MCU is reporting the error, then check the corresponding USB / CAN connection path.
2. With power off, reconnect the USB cable, replace it with a high-quality USB cable, and test using a different USB port on the host.
3. Execute ls /dev/serial/by-id/* to confirm whether the device is still present in the system; if the device is gone, the issue is at the power supply, cable, or MCU reset level.
4. Check whether the mainboard and toolboard power supply is stable, confirming normal voltage drop on the power wires (do not disassemble the power supply or modify mains wiring yourself).
5. If Unable to issue reset command on MCU also appears in the log, handle it together with reference to Unable to issue reset command.
6. If related to a CAN toolboard, check the bus status according to CAN Error Troubleshooting.
7. If the problem recurs, continue troubleshooting with reference to Lost communication with MCU.

Timeout on wait for 'xxx' response

Error Message: Timeout on wait for 'neopixel_result' response, Timeout on wait for 'trsync_state' response, etc.

Common Causes:

• Unstable CAN / USB communication link, where the MCU fails to respond to host requests in time.
• Excessive load on the MCU (e.g., high-speed printing combined with multi-axis motion and accelerometer queries occurring simultaneously).
• Too many Neopixel LEDs or poor data cable quality, causing neopixel_result timeouts.
• Firmware version mismatch between the MCU and the host.

Solutions:

1. Check whether the USB / CAN communication cable connection is secure, keeping it away from interference sources such as motor wires and heater wires.
2. For Neopixel timeouts, reduce the number of LEDs or replace with a higher-quality data cable, and confirm the data_pin configuration is correct.
3. Confirm all MCU firmware versions are consistent, and recompile and reflash if necessary.
4. Reduce print speed and acceleration to observe whether the issue reproduces.

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 toolboard firmware was not recompiled and reflashed.
• Firmware version mismatch between peripheral MCUs (mainboard, toolboard, EDDY, ADXL, etc.) and the host-side Klipper.
• Use of a custom system or third-party plugins causing inconsistency between the commands supported by the Klipper host and the MCU.

Solutions:

1. Check whether Klipper, the system image, or plugins have been updated recently.
2. Recompile and reflash the Klipper firmware for all MCUs.
3. For peripheral MCUs such as toolboards, EDDY, or ADXL, update the corresponding peripheral firmware accordingly.
4. If using a custom system, confirm that it supports the current Klipper version.
5. After reflashing, execute FIRMWARE_RESTART and then reconnect for testing.

I2C Communication Errors (START_READ_NACK / BUS_TIMEOUT)

Error Message: MCU 'xxx' I2C request to addr 42 reports error START_READ_NACK, I2C request to addr 104 reports error START_READ_NACK, or I2C ... BUS_TIMEOUT.

Common Causes:

• Incorrect I2C device address configuration, or no device with the corresponding address on the bus.
• Loose, broken I2C wiring, or SDA/SCL swapped.
• Missing pull-up resistors, or signal degradation due to overly long bus lines.
• The sensor is read before it is ready (e.g., queried immediately after power-on).
• Address conflict between multiple I2C devices.

Solutions:

Power Off Before Operation

Before checking I2C wiring, sensor modules, or pull-up resistors, completely shut down the printer and disconnect the power supply.

1. After powering off, check whether the I2C wiring (SDA, SCL, VCC, GND) is secure and confirm that the wires are not swapped.
2. Verify that the I2C address in the configuration matches the actual device. Common addresses: ADXL345 is 0x53 (83) or 0x1D (29), MPU6050 is 0x68 (104).
3. Check whether there are pull-up resistors (typically 4.7kΩ) on the I2C bus; if the module has built-in pull-ups, no additional ones are needed.
4. If the bus is long (over 30cm), try shortening the wiring or lowering the I2C speed.
5. If the error occurs only once at startup, it may be due to sensor initialization delay; observe whether it operates stably afterwards.
6. Ensure that no two devices on the same I2C bus use the same address.

EDDY Probe I2C Error: If BUS_TIMEOUT occurs with the EDDY eddy current probe, refer to the EDDY Troubleshooting Compilation.

Specialized FAQ

Category	Entry
Configuration conflicts, parameter parsing, SAVE_CONFIG	Configuration-related Errors
Unknown commands, macro templates, slicer start G-code	Configuration-related Errors
Motion, homing, endstops, probes, mesh bed leveling	Motion, Endstop, and Leveling Errors
Sensorless homing, virtual_endstop, DIAG sensitivity	Sensorless Homing Troubleshooting, Sensorless Usage
Temperature, heating, extrusion, filament runout detection	Temperature, Heating, and Extrusion Errors
Performance, timeouts, firmware, system services	System, Performance, and Service Errors
G2/G3, arc fitting, slicer path accuracy	Arc Fitting Recommendations
TMC driver communication, overheating, coil issues	TMC Error Troubleshooting
CAN network, UUID, bytes_invalid	CAN Network and ID Search
Accelerometer and resonance testing	Accelerometer Testing and Calibration
EDDY eddy current probe	EDDY Troubleshooting Compilation
Load Cell, pressure sensing probes	Load Cell Probe Troubleshooting