Skip to main content

Common Error Overview

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

Quick Index​

Error TypeCommon KeywordsTroubleshooting Entry
Connection IssuesUnable to connect, Invalid CAN uuid, Lost communication, MCU Protocol error, /dev/serial/by-id, Unable to issue reset command, Got EOF when reading from deviceThis page's Connection Issues, MCU ID Configuration, CAN Network and ID Search
Configuration Issuesnot valid, not a valid config section, must be specified, Unable to parse, SAVE_CONFIG, Option conflict, virtual_sdcard, pause_resume, display_statusConfiguration Errors
Macro and Slicer CommandsUnknown command, Error evaluating 'gcode_macro, jinja2.exceptions.UndefinedError, dict object has no attributeConfiguration Errors
Motion HomingMove out of range, Must home axis first, No trigger, Endstop still triggered, virtual_endstop, Unknown pin chip name, Homing failed due to printer shutdownMotion, Endstop, and Bed Leveling Errors, Sensorless Homing Troubleshooting
G-code ParsingUnable to parse move, Invalid speed, Machine does not support G20, G2/G3Motion, Endstop, and Bed Leveling Errors, Arc Fitting Recommendations
Probe Bed LevelingProbe triggered, No trigger on probe, samples_tolerance, bed_mesh, BLTouch failed, Z_TILT, QUAD_GANTRY_LEVEL, no samples between time, SVD did not convergeMotion, Endstop, and Bed Leveling Errors, BLTouch Configuration and Troubleshooting
Temperature HeatingADC out of range, not heating at expected rate, Verify heater, temperature, Thermocouple reader faultTemperature, Heating, and Extrusion Errors
Extrusion IssuesExtrude below minimum temp, Extrude only move too long, Move exceeds maximum extrusion, Filament sensor, M600Temperature, Heating, and Extrusion Errors
Performance TimeoutsTimer 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 activeSystem, Performance, and Service Errors
TMC DriversUnable to read tmc uart, Unable to write tmc spi, GSTAT, coil short circuit, tmcuart_responseTMC Error Troubleshooting
CAN Networkbytes_invalid, Network is down, No buffer space available, Invalid CAN uuid, USB CANBUS bridge, BUS-OFFCAN Network and ID Search, CAN Error Troubleshooting
Sensor PeripheralsInvalid adxl345 id, No data, Insufficient axis, Eddy current sensor error, Invalid read data, load_cell_probe, START_READ_NACK, I2C, BUS_TIMEOUTAccelerometer Testing and Calibration, EDDY Issue Collection, Load Cell Probe Troubleshooting, This page's I2C Communication Errors
Resonance Compensation and Pressure Advanceshaper_freq, input_shaper, pressure_advance, smooth_time, accel_chip, TEST_RESONANCES, SHAPER_CALIBRATEResonance Compensation and Pressure Advance
Error DirectionRecommended Reference
Configuration syntax, indentation, comments, duplicate pinsConfiguration Modification Instructions
Homing direction, axis direction, forced movementHoming and Direction Calibration Guide
Endstops, TAP, optical endstops, proximity switchesEndstop Related
Sensorless homing, virtual endstop sensitivitySensorless Usage
Heating, PID, slow heating, temperature protectionHeating Related, verify_heater Optimization, M109 Optimization
Fan configuration, driver fans, 7040 fansFan Reference Configuration
Extruder parameters, rotation distance, extrusion configurationExtruder Reference Configuration, Machine Calibration
Start/end macros, pause/resume, bed leveling and mesh macrosMacro Introduction
Common debugging commands, probes, resonance compensationCommon Debugging 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 MethodConfiguration ItemExample
USB Firmwareserial:serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx
CAN Firmwarecanbus_uuid:canbus_uuid: xxxxxxxxxxxx
Host MCUserial: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 motherboard.

Loading...

Common causes:

  • The USB device ID is not filled in or is filled in incorrectly.
  • The 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 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 UTOC device, USB bridge CAN firmware, or CAN0 device is missing.

    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 and ID Search.

mcu 'mcu': Invalid CAN uuid​

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

Loading...

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

Solution:

  1. Re-search the CAN UUID according to CAN Network and ID Search.
  2. Confirm that the UUID filled in printer.cfg is 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 baud rate.

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

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

Loading...

Cause of error: 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
  1. Save and restart Klipper.

If the current motherboard is flashed with CAN firmware, use canbus_uuid: and do not continue to fill in serial:.

USB ID not found / System service interference​

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

Common causes:

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

Troubleshooting steps:

Power Off Operation

Before re-plugging the USB cable, checking the motherboard power wiring, or organizing the USB / CAN wiring harness, completely turn off the printer and disconnect the power supply. Do not organize interface wiring or touch terminals while the power is on.

  1. First, confirm that the motherboard has been flashed 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. After powering off, replace the USB cable and host USB port with reliable ones. After powering back on, execute ls /dev/serial/by-id/* again.
  3. If using Debian 11 Bullseye, older versions of MainsailOS / FluiddPi / Armbian, or similar systems, run the following command to check the udev version:
apt-cache policy udev
  1. If the issue is confirmed to be a Debian 11 udev problem, first prioritize upgrading udev through the system's normal update sources, or switch to a newer system image.
  2. Check for services that may seize the serial port:
systemctl list-units --all | grep -Ei 'ModemManager|brltty'
  1. If these services are confirmed to be installed, and the current host does not require modem or braille terminal functionality, replace the full unit names shown in the previous command's output into the commands below, then stop, disable them, and reboot the system:
sudo systemctl disable --now ModemManager.service
sudo systemctl disable --now brltty.service
sudo systemctl disable --now brltty.path
  1. After completion, re-query the USB ID and confirm that the serial: in the [mcu] section of printer.cfg matches the actual output.

Related configuration reference: MCU ID Configuration.

Serial connection closed​

Error message: mcu 'xxx': Serial connection closed, the serial connection between Klipper and the MCU has closed unexpectedly.

Common causes:

  • The USB cable has poor contact or is of low quality.
  • The CAN bridge device (UTOC, etc.) has unstable power supply or abnormal firmware.
  • Power fluctuations on the motherboard cause the MCU to restart.
  • Abnormal CAN network communication, causing the device to go offline.

Solution:

  1. After powering off, re-plug the USB / CAN cables and replace them with reliable connection cables.
  2. Check the power supply and firmware status of the CAN bridge device, and re-search the CAN ID if necessary.
  3. Confirm the motherboard power supply is stable, and avoid sharing the power circuit with high-power devices.
  4. If the problem persists, refer to CAN Error Troubleshooting and Lost communication with MCU for further investigation.

Lost communication with MCU​

Error message: Communication between Klipper and the MCU is interrupted. The log may show Lost communication with MCU, Lost communication with mcu, or similar prompts.

Common scenarios: During homing or movement, the motherboard or toolboard goes offline as soon as the endstop is triggered; it can connect again after a power cycle.

Common causes:

  • Incorrect endstop switch wiring, causing an abnormal short circuit between the signal pin and power or ground when triggered.
  • When using three-wire endstops, optical endstops, or hall effect endstops, the power, ground, and signal wires are connected in the wrong order.
  • The endstop wiring harness is damaged, pinched, or short-circuits during cable chain movement.
  • The endstop trigger causes a power fluctuation on the motherboard, causing the MCU to restart or the USB / CAN communication to be interrupted.
  • The USB / CAN communication lines between the MCU and the host pass near strong interference sources, making disconnections more likely when triggering endstops or during movement.
  • The endstop pins in the configuration do not match the actual wiring, triggering the wrong interface.

Troubleshooting steps:

Power Off Operation

Before unplugging endstop wires, checking the wiring order, inspecting the cable chain harness, or using a multimeter to measure continuity/resistance, completely turn off the printer and disconnect the power supply. The multimeter resistance/continuity mode can only be used when the power is off. It is forbidden to measure resistance or perform short circuit tests while the power is on.

  1. After powering off, check the endstop switch wiring order, especially whether the VCC, GND, and Signal of a three-wire endstop are connected incorrectly.
  2. After powering off, temporarily unplug the corresponding endstop wire. After reassembling, power on the machine again to test whether the motherboard still goes offline.
  3. After powering off, use the multimeter's continuity/resistance mode to check for short circuits before and after the endstop is triggered, focusing on whether the signal pin is connected to power.
  4. Check the cable chain, connectors, and bending points of the wiring harness to make sure the wiring is not pinched or short-circuited during triggering or movement.
  5. Check the USB / CAN communication lines between the MCU and the host, and keep them away from motor wires, heater wires, heated bed wires, and power wires as much as possible.
  6. If the machine's enclosure, power supply, or shielding is not reliably grounded, it may also be more susceptible to interference; only confirm the grounding point and socket status provided by the manufacturer, and do not disassemble the power supply or modify the mains ground wire yourself.
  7. Confirm that the endstop pins in the configuration match the motherboard documentation and actual wiring.
  8. After the issue is fixed, run QUERY_ENDSTOPS to confirm the endstop status can change from open to TRIGGERED correctly. For related configuration, refer to: Limit-related, Power Wiring Instructions.

Unable to issue reset command on MCU​

Error message: Unable to issue reset command on MCU 'xxx'. The log usually also contains webhooks client ...: Disconnected and Restarting printer.

Nature of the error: This error is generally not the first error to appear, but rather a subsequent notification when Klipper fails to send a reset command to the MCU after it has gone offline, lost power, or experienced a communication interruption. When troubleshooting, you should 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 went offline, USB/CAN communication was interrupted, or the firmware crashed, preventing the reset command from being delivered.
  • Insufficient power supply to the mainboard, toolhead board, or peripheral MCU, causing a power loss during the reset process.
  • Poor contact or damaged USB cables or CAN cables.
  • The MCU was forcibly reset while executing a high-load task (such as heating or multi-point bed probing).
  • Strong signal interference between the host and the MCU (motor wires or heater wires running close to communication wires).

Solutions:

Power-off procedure

Before re-plugging USB/CAN cables, inspecting wires, or organizing cable routing, completely shut down the printer and disconnect the power supply. Do not plug or unplug cable bundles or touch terminals while the printer is powered on.

  1. Open klippy.log, find the first real error before Unable to issue reset command, and troubleshoot according to the corresponding category.
  2. After powering off, re-plug the USB/CAN cables, replace them with reliable commercial-grade cables, and confirm the connections are secure.
  3. Check whether the power supply to the mainboard and toolhead board is stable, and avoid sharing an unstable power circuit with motors and high-power devices such as 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, and if necessary, power off the entire machine for 10 seconds before powering it back on.
  6. If the problem recurs, continue troubleshooting by referring to Lost communication with MCU and CAN Error Troubleshooting.

Got EOF when reading from device​

Error message: Got EOF when reading from device. In the log, this usually appears after Attempting MCU 'xxx' reset command, indicating that the serial/USB connection was already disconnected when the host attempted to reset 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) marker read by pyserial. It indicates that the USB/serial link has been physically disconnected or the device has disappeared, rather than a configuration parameter issue.

Common causes:

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

Solutions:

Power-off procedure

Before re-plugging USB/CAN cables, inspecting power wires, 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 link.
  2. After powering off, re-plug the USB cable, replace it with a high-quality USB cable, and try a different USB port on the host.
  3. Run ls /dev/serial/by-id/* to confirm whether the device is still present in the system; if the device has disappeared, it indicates a power supply, cable, or MCU reset issue.
  4. Check whether the power supply to the mainboard and toolhead board is stable, and confirm that the voltage drop on the power wires is normal (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, refer to Unable to issue reset command as well.
  6. If the issue is related to a CAN toolhead board, check the bus status according to CAN Error Troubleshooting.
  7. If the problem recurs, continue troubleshooting by referring 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 a timely manner.
  • Excessive MCU load (e.g., high-speed printing + multi-axis motion + accelerometer queries running simultaneously).
  • Too many Neopixel LEDs or poor data cable quality, causing neopixel_result timeouts.
  • MCU firmware version mismatch with the host.

Solutions:

  1. Check whether the USB/CAN communication cables are securely connected, and keep them away from sources of interference such as motor wires and heater wires.
  2. If the timeout is Neopixel-related, reduce the number of LEDs or replace the data cable with a higher quality one, and confirm the data_pin configuration is correct.
  3. Confirm that 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 contain MCU Protocol error, Unknown command, or Command format mismatch.

Loading...

Common causes:

  • The host Klipper was updated, but the mainboard or toolhead board firmware was not recompiled and reflashed.
  • Firmware version mismatch between peripheral MCUs (mainboard, toolhead board, EDDY, ADXL, etc.) and the host Klipper.
  • Use of a custom system or third-party plugins, causing inconsistencies between the commands supported by the Klipper host and the MCU.

Solutions:

  1. Confirm 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 toolhead boards, EDDY, and ADXL, update the corresponding peripheral firmware synchronously.
  4. If using a custom system, confirm that the system supports the current Klipper version.
  5. After flashing, execute FIRMWARE_RESTART and then reconnect for testing.

I2C Communication Error (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 exists at the corresponding address on the bus.
  • Loose, broken, or reversed SDA/SCL I2C wiring.
  • Missing pull-up resistors, or signal degradation due to an excessively long bus.
  • Reading a sensor before it is ready (e.g., querying immediately after power-on).
  • Address conflicts between multiple I2C devices.

Solutions:

Power-off procedure

Before inspecting 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 SDA and SCL are not reversed.
  2. Confirm that the configured I2C address matches the actual device. Common addresses: ADXL345 is 0x53 (83) or 0x1D (29), MPU6050 is 0x68 (104).
  3. Check whether the I2C bus has pull-up resistors (typically 4.7kΩ); 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 reducing the I2C speed.
  5. If the error occurs only once at startup, it may be a sensor initialization delay; observe whether it operates stably afterward.
  6. Confirm that no two devices on the same I2C bus are using the same address.

EDDY Probe I2C Error: If you encounter BUS_TIMEOUT with the EDDY eddy current probe, refer to EDDY Issue Collection.

Specialized FAQ​

TopicEntry
Configuration conflicts, parameter parsing, SAVE_CONFIGConfiguration Errors
Unknown commands, macro templates, slicer start G-codeConfiguration Errors
Motion, homing, limits, probes, mesh bed levelingMotion, Limit & Leveling Errors
Sensorless homing, virtual_endstop, DIAG sensitivitySensorless Homing Troubleshooting, Sensorless Usage
Temperature, heating, extrusion, filament runout detectionTemperature, Heating & Extrusion Errors
Performance, timeouts, firmware, system servicesSystem, Performance & Service Errors
G2/G3, arc fitting, slicer path precisionArc Fitting Recommendations
TMC driver communication, overtemperature, coil issuesTMC Error Troubleshooting
CAN network, UUID, bytes_invalidCAN Network & ID Search
Accelerometer and resonance testingAccelerometer Testing & Calibration
EDDY eddy current probeEDDY Issue Collection
Load Cell, pressure sensing probeLoad Cell Probe Troubleshooting
Loading...