Skip to main content

Common Error Prompts

This page is used for quickly locating common Klipper errors. First, find the complete error in klippy.log, then check the corresponding explanation.

Connection Issues​

mcu 'xxx': Unable to connect​

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

Loading...

Common Causes:

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

Solutions:

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

  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 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, 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 unrecognizable.

Loading...

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

Solutions:

  1. Re-search the CAN UUID according to CAN Network and ID Search.
  2. Confirm that the UUID entered in printer.cfg matches the one found.
  3. Confirm that 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] configuration section.

Loading...

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

Solutions:

  1. Re-search for the USB device ID.
  2. Fill in the [mcu] section of printer.cfg:
[mcu]
serial: /dev/serial/by-id/actual ID found
  1. Save and restart Klipper.

If the current mainboard is flashed with CAN firmware, please use canbus_uuid: and do not fill in serial:.

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, when the endstop is triggered, the mainboard or toolboard goes offline; it can reconnect after power cycling.

Common Causes:

  • Incorrect endstop switch wiring, causing abnormal short circuit of the signal pin with power or ground upon triggering.
  • Incorrect order of power, ground, and signal wires when using three-wire, optical, or Hall effect endstops.
  • Damaged wire insulation, pinched wires, or short circuits during cable chain movement.
  • Power supply fluctuation upon endstop trigger, causing MCU restart or USB/CAN communication interruption.
  • USB/CAN communication cables between MCU and host passing near strong interference sources, making disconnection more likely when endstop is triggered or during movement.
  • The endstop pin configured does not match the actual wiring, triggering the wrong interface.

Troubleshooting Steps:

  1. Power off and check the endstop switch wiring, especially whether VCC, GND, and Signal of three-wire endstops are reversed.
  2. Temporarily disconnect the corresponding endstop wire, then power on again to test if the mainboard still goes offline.
  3. Use a multimeter to check for short circuits before and after endstop triggering, focusing on whether the signal pin is connected to power.
  4. Check cable chains, connectors, and wire bending points to ensure no pinching or short circuits during triggering or movement.
  5. Check the USB/CAN communication cable between MCU and host, keeping it away from motor wires, heater wires, bed wires, and power cables as much as possible.
  6. If the machine chassis, power supply, or shielding is not reliably grounded, it may be more susceptible to interference. Check grounding according to equipment electrical safety requirements.
  7. Confirm that the endstop pins configured match the mainboard documentation and actual wiring.
  8. After fixing the issue, run QUERY_ENDSTOPS to confirm the endstop state can normally change from open to TRIGGERED.

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 Klipper was updated, but the mainboard or toolboard firmware was not recompiled and flashed.
  • Firmware versions of peripherals like mainboard, toolboard, EDDY, ADXL do not match the host Klipper version.
  • Using a custom system or third-party plugin causing command mismatch between Klipper host and MCU.

Solutions:

  1. Confirm whether Klipper, system image, or plugins have been updated recently.
  2. Recompile and flash the corresponding MCU's Klipper firmware.
  3. For peripheral MCUs like toolboard, EDDY, ADXL, update their firmware synchronously.
  4. If using a custom system, confirm it supports the current Klipper version.
  5. After flashing, execute FIRMWARE_RESTART and test the connection again.

Configuration Conflict Issues​

homing override method always homes X and Y before homing Z. The safe_z_home​

Error Message: Safe Z homing conflicts with homing override configuration.

Loading...

Cause of Error: Both [safe_z_home] and [homing_override] are configured, causing Klipper to be unable to determine which homing logic to use.

Solutions:

  1. Search for [safe_z_home] and [homing_override] in the configuration file.
  2. Keep only one of them based on the machine's actual homing logic.
  3. Save and restart Klipper.

Motion and Homing Issues​

Move out of range​

Error Message: The target coordinate is outside the motion range allowed by Klipper. The log usually shows something like Move out of range: X Y Z [E].

Loading...

Common Causes:

  • The machine size in the slicer does not match the position_min / position_max in the Klipper configuration.
  • Start G-code, end G-code, filament change macro, or pause macro moves outside the machine's range.
  • The park position in macros like M600, PAUSE, CANCEL_PRINT is too close to the boundary.
  • After using skew correction, probe offset, or mesh leveling configuration, the actual calculated coordinate becomes negative or exceeds the maximum travel.
  • The model height exceeds the Z-axis maximum travel.

Solutions:

  1. Determine which axis is out of range based on the coordinates in the error.
  2. Check the position_min, position_max for the corresponding axis and the slicer machine size.
  3. Check park coordinates in start, end, pause, filament change macros, avoiding 0,0 or maximum boundaries.
  4. If the error occurs during mesh leveling, check mesh_min, mesh_max, and probe offset in [bed_mesh].
  5. Save the configuration, restart Klipper, and retest.

Must home axis first​

Error Message: The axis has not been homed and cannot execute the current movement command.

Common Causes:

  • G28 was not executed after power-on or FIRMWARE_RESTART.
  • A movement command is executed before a homing command within a macro.
  • Machine state is reset after print pause, resume, or cancel.
  • Homing macro, probe macro, or sensorless homing configuration is abnormal, causing Klipper not to record the homed state correctly.

Solutions:

  1. Manually execute G28 before moving the corresponding axis.
  2. Check the start G-code and macros to ensure homing is completed before movement commands.
  3. If Klipper or firmware was just updated, check if the homing-related macros are still compatible.
  4. If using sensorless homing, check driver current, sensitivity, and homing_retract_dist.

Endstop still triggered after retract​

Error Message: After homing triggers the endstop and the retract distance ends, the endstop is still in a triggered state.

Common Causes:

  • The endstop switch NO/NC logic is configured inversely.
  • The endstop switch is stuck, damaged, or wrongly wired.
  • homing_retract_dist is too small, still pressing the endstop after retraction.
  • Sensorless homing sensitivity is too high, still judged as triggered after retraction.
  • Incorrect configuration of driver enable_pin, motor direction, or endstop pin, causing abnormal homing action.

Solutions:

  1. Run QUERY_ENDSTOPS to confirm it shows open when not triggered and TRIGGERED when manually triggered.
  2. If the state is reversed, adjust the ! before the endstop pin.
  3. Check the mechanical state, wiring, and connector of the endstop switch.
  4. Increase homing_retract_dist appropriately and retest.
  5. If using sensorless homing, lower the sensitivity and ensure the homing current is appropriate.

No trigger on probe after full movement​

Error Message: The probe did not trigger within the full probing travel range.

Common Causes:

  • Incorrect probe wiring, power supply, or pin configuration.
  • Improper probe mounting height, unable to trigger within the probing travel.
  • Incorrect Z-axis direction, probe offset, or leveling area configuration.
  • Probe hardware failure, or poor contact in the wiring during movement.
  • The bed, nozzle, or probe position is outside the detectable range.

Solutions:

  1. Run QUERY_PROBE and manually trigger the probe to confirm the state changes correctly.
  2. Check the probe power supply, signal wire, and configured pins.
  3. Check the probe mounting height to ensure it is within the triggerable range before probing.
  4. Check if the probing points in [probe], [bed_mesh], [z_tilt], or [quad_gantry_level] are beyond the bed.
  5. If the problem only occurs at certain positions, pay special attention to wiring drag and probe offset.

Temperature Detection Issues​

Error 'XXX mcu' shutdown: ADC out of range​

Error Message: ADC is out of range, temperature detection is abnormal.

Loading...

Cause of Error: Klipper detected a temperature outside the configured allowed range. Common causes include thermistor open circuit, short circuit, wiring error, incorrect thermistor model configuration, or pin configuration error.

Note

Temporarily relaxing min_temp and max_temp is only for troubleshooting and should not be used as a long-term configuration. After confirming the problem, it must be restored to a safe range to avoid temperature protection failure.

Troubleshooting Order:

  1. Check if the thermistor is firmly plugged in and if the wire is broken or shorted.
  2. Check if the thermistor model and pin configuration match the actual hardware.
  3. If necessary, temporarily relax the temperature range to confirm the reading changes, e.g., lower min_temp, raise max_temp.
  4. After finding and fixing the wiring or configuration issue, immediately restore the original safe temperature limits.
  5. Save and restart Klipper.

Heater not heating at expected rate​

Error Message: The heater is not heating up at the expected rate. The log may show Heater extruder not heating at expected rate or Heater heater_bed not heating at expected rate.

Loading...

Common Causes:

  • Abnormal output from the heater cartridge, heated bed, or SSR/MOSFET.
  • Poor contact of the thermistor, broken wire, or fluctuating readings.
  • Fan blowing directly on the hotend, heated bed, or heating area, causing slow heating.
  • Insufficient power for the heated bed, or max_power limit is too low.
  • Inappropriate PID parameters, excessive fluctuation near the target temperature.

Solutions:

  1. Check if the heater and thermistor wiring is secure.
  2. Observe the temperature curve to see if the heating is continuous and if there are abnormal fluctuations.
  3. Check if any fan blows directly on the hotend or heated bed.
  4. Check heater power, power supply, fuse, SSR/MOSFET, and max_power settings.
  5. After confirming the hardware is normal, re-run PID calibration.
  6. If it is confirmed that the slow heating is simply due to a large bed or special structure, refer to verify_heater optimization.

Extrusion Issues​

Extrude below minimum temp​

Error Message: The nozzle temperature is below the minimum temperature allowed for extrusion. The log may show Extrude below minimum temp or Extruder not hot enough.

Common Causes:

  • An extrusion command is executed without heating the nozzle.
  • Start G-code, filament change macro, or pause/resume macro lacks a temperature wait command.
  • The target temperature has not been reached, and the macro executes extrusion or retraction prematurely.
  • Abnormal temperature sensor readings cause Klipper to judge the nozzle has not reached the extrudable temperature.

Solutions:

  1. Before extruding, ensure the nozzle has reached the required temperature for the filament.
  2. Check if macros like start G-code, M600, PAUSE, RESUME have temperature wait logic.
  3. Use M109 or the Klipper equivalent wait command where temperature wait is needed.
  4. Check the thermistor and temperature curve to ensure stable temperature readings.
  5. It is not recommended to permanently lower min_extrude_temp to bypass the error.

Performance and Timeout Issues​

Homing Timeout Issues​

If communication timeout, MCU disconnection, or multi-MCU homing anomalies occur during homing, refer to Homing Timeout Issues.

MCU 'mcu' shutdown: Stepper too far in past​

Error Message: The stepper event is beyond the time range the MCU can handle, causing the printer to enter shutdown state.

Loading...

Reference Scenarios: This error is not necessarily caused by bed mesh configuration. The actual cause needs to be determined by considering klippy.log and the current operation. When performing multi-point probing, if probe_count in [bed_mesh] is set too high, e.g., 20,20, and a high mesh_pps is also configured, e.g., mesh_pps: 4,4, it may generate overly dense mesh data, increasing host computation and motion planning pressure, potentially triggering this error.

Solutions:

  1. If the error occurs during multi-point probing, first reduce probe_count in [bed_mesh], e.g., test with 7,7 or 9,9.
  2. If a high mesh_pps is configured, reduce or remove this configuration, e.g., change to mesh_pps: 2,2; if interpolation is not needed, set it to 0,0 as needed.
  3. Save the configuration, restart Klipper, and re-run the operation that triggered the error.
  4. If the error persists, continue checking host load, print speed, acceleration, communication quality, and currently executing macros or G-code.

MCU 'mcu' shutdown: Timer too close​

Error Message: The MCU timer is too close, causing a system timeout.

Loading...

Cause of Error: High processing load on the MCU, host response timeout, excessively high print speed, excessively high micro-stepping, system time synchronization interference, or interference on the MCU communication line can all trigger this issue.

Solutions:

  1. Reduce stepper motor micro-stepping to decrease MCU pulse processing pressure.
  2. Reduce print speed and acceleration to see if the problem disappears.
  3. Check host load, power supply, and USB/CAN communication quality.
  4. Check if the communication cable between the MCU and host is near motor wires, heater wires, bed wires, or power cables; reroute or use shielded communication cables if necessary.
  5. Check machine grounding; machines without reliable grounding are more prone to communication interference.
  6. If the problem occurs during homing, refer to Homing Timeout Issues.
  7. If the problem persists, consider re-flashing the host system or firmware.

Raspberry Pi users can check NTP time synchronization status:

sudo timedatectl status | grep "NTP service"

To temporarily disable NTP synchronization, run:

sudo timedatectl set-ntp false

After confirming the problem is not related to NTP, re-enable it as needed:

sudo timedatectl set-ntp true
Loading...