Skip to main content

System, Performance, and Service Errors

This page covers communication timeouts, MCU timing errors, host performance, firmware flashing, and Klipper service startup issues.

Homing Timeout Issues​

Error Message: Communication timeout during homing or Error during homing xxx appears during the homing process. Commonly occurs in multi-MCU Z-axis homing scenarios.

Common Causes:

  • High host load, with KlipperScreen, camera streams, etc., running simultaneously.
  • Multiple axis motors moving simultaneously during homing, where large current drive signals couple into CAN/USB communication lines, causing communication interruptions.
  • Unstable communication responses from multiple MCUs.
  • Poor quality or improper routing of CAN/USB communication cables.

Solutions:

Power Off Operation

Before reorganizing CAN/USB cable routing, checking shielding, or inspecting grounding, completely shut down the printer and disconnect the power supply. Do not modify the power ground wire, mains wiring, or internal power supply structure yourself.

  1. First, eliminate electromagnetic interference: Check if CAN/USB cables are routed separately from motor and heater cables. Refer to the interference troubleshooting steps in CAN Network Configuration and ID Search.
  2. Try adjusting the TRSYNC_TIMEOUT parameter or temporarily disable KlipperScreen. See Homing Timeout Issues for details.
  3. Check if the machine grounding and shield grounding are normal.

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

Error Message: Klipper's planned stepper events to send to the MCU have fallen behind the current time. The MCU can no longer execute these motion commands at the intended time, causing the printer to enter a shutdown state.

Loading...

Cause: This is usually not caused by a single fixed configuration item, but rather a result of the host-side motion planning, MCU stepping output, or communication scheduling being unable to keep up. High host load, excessive print speed/acceleration, high micro-stepping, multi-MCU communication latency, poor USB/CAN communication quality, and macros or G-code generating a large number of motion commands in a short time can all trigger this issue.

Reference Scenario: When performing multi-point bed mesh probing, if probe_count in [bed_mesh] is set too high, and a high mesh_pps is also configured, overly dense mesh data may be generated, increasing host computational and motion planning load. This is just one common scenario; even without bed probing, other situations that increase system load or communication latency can also lead to Stepper too far in past.

Scenario After Resume: The error can also occur after PAUSE / RESUME, filament runout recovery, or power-loss resume. Typical log behavior shows: After recovery, the buffer_time in Stats lines drops sharply from ~1s to around 0.2s, sd_pos almost stops increasing (print progress stalls), but sysload is not high, and no MCU is disconnected. This indicates that motion commands are not continuously filling the step buffer after recovery; the printer "started printing but barely moved" before entering shutdown. During troubleshooting, focus on checking if the recovery/resume macro (resume_gcode, start_gcode) sends abnormal long moves or retraction commands immediately upon resume, and whether communication retransmissions (bytes_retransmit) existed before the recovery.

Solutions:

  1. First, check the Stats lines just before the error in klippy.log to confirm if there are simultaneous occurrences of high CPU usage, bytes_retransmit, bytes_invalid, Timer too close, MCU disconnection, or queue anomalies.
  2. Temporarily disable camera streams, KlipperScreen, remote control plugins, and other high-load services. Retest after reducing host load.
  3. Lower print speed, acceleration, and micro-stepping. Observe if the error disappears.
  4. If the error occurs during multi-point bed probing, reduce probe_count in [bed_mesh], e.g., try 7,7 or 9,9.
  5. If a high mesh_pps is configured, lower or remove this setting, e.g., change to mesh_pps: 2,2.
  6. Check USB / CAN communication quality; if using CAN, verify queue length, termination resistors, wiring order, power supply, and firmware CAN bitrate.
  7. Review the macro or G-code running just before the error trigger. Avoid macro loops, overly dense short segments, or abnormal scripts sending many motion commands in a short time.

Related configuration reference: Macros, Common Debug Directives.

MCU 'mcu' shutdown: Timer too close​

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

Loading...

Cause: High load on the microcontroller (MCU), host response timeout, excessive print speed, high micro-stepping, system time synchronization interference, or interference on MCU communication lines can all trigger this issue.

Common Recent Scenarios:

  • M600, PAUSE, RESUME, filament runout detection, or filament change macros causing a delay before resuming, followed by Timer too close.
  • EDDY / TAP / CAN toolboard participation in Z-homing, Z_TILT_ADJUST, QUAD_GANTRY_LEVEL, or bed probing, with concurrent CAN retransmissions, abnormal I2C readings, or host load spikes in the logs.
  • Insufficient scheduling headroom when running cameras, KlipperScreen, and remote control plugins simultaneously on multi-toolhead, multi-CAN node, or low-performance host systems.

Solutions:

  1. Reduce stepper motor micro-stepping to decrease MCU pulse processing load.
  2. Lower print speed and acceleration. Observe if the problem disappears.
  3. Check host load, power supply, and USB / CAN communication quality.
  4. After powering off, check if the communication cable between the MCU and the host is routed near motor, heater, heated bed, or power supply cables. Re-route or replace with shielded communication cables if necessary.
  5. When checking machine grounding, only verify the grounding point provided by the manufacturer and the socket condition. Do not disassemble the power supply or modify the mains ground wire.
  6. If the problem occurs during the homing phase, refer to Homing Timeout Issues.
  7. If it occurs after M600 or filament runout recovery, check if the macro contains redundant PAUSE commands, if the filament sensor is falsely triggered during the filament change process, and if the SAVE_GCODE_STATE / RESTORE_GCODE_STATE names match.
  8. If it occurs during EDDY TAP, Z-tilt, or gantry leveling, first refer to EDDY TAP Mode Debugging.
  9. If the problem persists, consider re-flashing the host system or firmware.

Related configuration reference: Common Debug Directives, Homing and Direction Calibration Guide.

MCU shutdown: Missed scheduling of next digital out event​

Error Message: MCU 'xxx' shutdown: Missed scheduling of next digital out event.

Cause: After Klipper on the host side activates a digital output like a heater or fan, the MCU needs to receive subsequent scheduling and acknowledgments on time. If the host load is too high, system scheduling is delayed, USB/CAN communication is unstable, or the CAN bus queue is abnormal, the MCU may not receive the next digital output event in time, leading to a shutdown state.

Note

This error relates to heater output scheduling. Do not bypass this error by disabling thermal protection, turning off verify_heater, or removing safety configurations. First, troubleshoot host load and communication quality.

Solutions:

  1. First, check the Stats lines just before this error in klippy.log to confirm if there are simultaneous records of bytes_retransmit, bytes_invalid, Timer too close, or MCU disconnection.
  2. Reduce host load by temporarily disabling camera streams, KlipperScreen, remote control plugins, or other high-load services.
  3. Check USB / CAN communication quality; if using CAN, verify CAN0 queue length, termination resistors, wiring order, power supply, and firmware CAN bitrate.
  4. Lower print speed, acceleration, and micro-stepping. Observe if the problem disappears.
  5. If the error occurs only when heating, also check the load on the heated bed, hotend, fans, and power supply. Do not disassemble the power supply or inspect the mains-powered bed wiring.
  6. If the problem originates from a CAN toolboard, proceed to CAN Error Troubleshooting.

Related configuration reference: Common Debug Directives, CAN Network and ID Search.

Rescheduled timer in the past​

Error Message: Rescheduled timer in the past or similar warnings appear in the log.

Cause: Issues with the host system clock or excessive CPU load causing the actual execution time of a scheduled task to lag behind its planned time.

Solutions:

  1. If NTP synchronization is enabled, temporarily disable it for testing.
  2. Reduce the load from other services running on the host, such as closing unnecessary web interfaces, camera streams, etc.
  3. If running in a virtual machine, consider migrating to a physical machine or using a more stable clock source.
  4. Check host CPU usage: Use htop to check if the klippy process has abnormally high CPU consumption. For related configuration, refer to: Common Debug Commands.

MCU 'mcu' shutdown: Move queue overflow​

Error Message: MCU 'mcu' shutdown: Move queue overflow.

Cause: The MCU motion queue is full, and the host has not synchronized motion planning and status to the MCU in time. This is commonly caused by insufficient host performance, a large number of small movements in a short period, version mismatch between Klipper host and MCU firmware, or vendor-customized Klipper that adds blocking logic like synchronous disk writes or power-loss recovery in each movement command.

Common Indicators:

  • In klippy.log, the base version of Git version differs significantly from Loaded MCU 'xxx' ... version.
  • Log entries contain dirty, third-party klippy/extras files, vendor-customized power-loss recovery, or non-official Klipper.
  • The same G-code file fails at a similar position, and the model contains many short segments, dense supports, spiral Z-hop, or complex paths.
  • A low-performance host is running a camera, display, remote control, or other high-load services simultaneously.

Solutions:

  1. View the full klippy.log first to confirm if there are earlier errors like Timer too close, CAN disconnection, bytes_invalid, or temperature/TMC errors.
  2. After updating Klipper, recompile and flash all MCU firmware to ensure the version matches between the host, mainboard, and toolboard firmware.
  3. Temporarily disable camera streams, KlipperScreen, remote control plugins, and other high-usage services, then retest.
  4. Reduce print speed, acceleration, or microstepping in firmware, or lower curve precision, support complexity, and short segment density in the slicer.
  5. If using vendor-customized power-loss recovery, automatic height recording, or third-party plugins, first test with original Klipper or disable the corresponding features for cross-testing. Do not modify Klipper source code directly as a routine step for regular users.
  6. If the issue occurs only with a specific G-code file, reslice it and check if the slicer produces abnormally dense paths.

For related configuration, refer to: Common Debug Commands, Arc Fitting Recommendations.

stepcompress / syncemitter / flush_handler Internal Error​

Error Messages: stepper.error: Internal error in stepcompress, stepcompress ... Invalid sequence, Error in syncemitter 'extruder' step generation, Exception in flush_handler, Flush Handler error.

Cause: Klipper encounters an internal exception when generating or compressing stepper pulses. In recent community cases, this issue often appears alongside high-speed probing, scanner/EDDY/Cartographer-type probe plugins, input_shaper, complex motion paths, or third-party Klipper modifications. It is not necessarily caused solely by the slicer and should not be diagnosed by reslicing alone.

Solutions:

  1. Keep the complete klippy.log, focusing on the Python Traceback, executing commands, and Stats lines before and after the error.
  2. If the error occurs during BED_MESH_CALIBRATE, QUAD_GANTRY_LEVEL, or scanner probing, first reduce probing speed, point count, interpolation density, and plugin scanning parameters.
  3. Temporarily disable third-party scanners, automatic speed adjustments, automatic leveling enhancements, macro packs, or vendor modifications. Retest with original Klipper.
  4. After updating Klipper, reflash all MCU firmware and confirm that peripheral firmware versions match the host Klipper version.
  5. If the same model repeatedly triggers the issue, reslice it to reduce short segment density. If the issue persists randomly after reslicing, continue troubleshooting based on host load, motion parameters, and plugin compatibility.
  6. If the printer exhibits abnormal motion, lost steps, or risk of collision, immediately execute an emergency stop and re-home. Do not resume the original task.

For related configuration, refer to: Motion, Endstop, and Leveling Errors, EDDY Issue Collection.

Internal error on command​

Error Message: Internal error on command:"XXX", Klipper enters shutdown state.

Common Causes:

  • A macro or G-code command triggers a Python exception inside Klipper.
  • Incorrect macro references or Jinja2 template syntax errors in the configuration file.
  • Version incompatibility between Klipper version and configuration file format.
  • Special characters in the G-code filename causing encoding errors.
  • Errors from stepcompress, syncemitter, or flush_handler interrupt command execution.

Solutions:

  1. View the full Python Traceback below the Internal error line in klippy.log.
  2. Based on the Traceback, identify which configuration file or macro has the issue.
  3. Common causes include Jinja2 template syntax errors in [gcode_macro], missing [respond] configuration, or incorrect [virtual_sdcard] path.
  4. If the error is related to SDCARD_PRINT_FILE and indicates ascii codec can't decode, change the G-code filename to use only English letters, numbers, underscores, or hyphens.
  5. If the Traceback contains stepcompress, syncemitter, or flush_handler, proceed to troubleshoot according to stepcompress / syncemitter / flush_handler Internal Error.

For related configuration, refer to: Macro Introduction, Configuration Modification Guide.

Unable to open file / SD busy​

Error Messages: Unable to open file, Unable to get file list, SD busy, SD write not supported, SDCARD_RESET_FILE cannot be run from the sdcard during file printing.

Common Causes:

  • The G-code file does not exist, its name has been changed, or the upload was incomplete.
  • The [virtual_sdcard] path points to an incorrect directory.
  • File permission issues prevent the Klipper user from reading it.
  • Special characters in the filename cause path handling issues for some frontends or systems.
  • Commands to open, select, reset, or write the virtual SD card are executed while a file is being printed or read.
  • The Klipper source directory, configuration directory, or other non-G-code directory is incorrectly set as the [virtual_sdcard] path.

Solutions:

  1. Re-upload the G-code file through the web interface and confirm the filename matches the print command.
  2. Check if the [virtual_sdcard] path points to the actual G-code storage directory.
  3. Check directory permissions: ls -la ~/printer_data/gcodes/.
  4. Change the filename to use only English letters, numbers, underscores, or hyphens, then test again.
  5. If SD busy is indicated, pause or cancel the current print first, and confirm no other macro is operating on the virtual SD file.
  6. Do not set ~/klipper, ~/printer_data/config, or a system directory as the G-code storage directory.

For related configuration, refer to: Configuration Modification Guide.

MCU CRC does not match config / Can not update MCU config​

Error Messages: MCU 'xxx' CRC does not match config, Can not update MCU 'xxx' config as it is shutdown, Unable to configure MCU 'xxx'.

Key Diagnosis Point: Can not update MCU 'xxx' config as it is shutdown is usually not the root cause. It is a subsequent error that appears when Klipper tries to reconnect or reconfigure an MCU that is already in shutdown/error state. When troubleshooting, do not only look at the last line of the log; scroll up to find the earliest first real error.

Solutions:

  1. Execute FIRMWARE_RESTART. If necessary, power off the entire machine for 10 seconds, then power it back on.
  2. In klippy.log, look for the earliest occurrence of shutdown, Timer too close, Lost communication, Verify heater, TMC, or temperature errors. Fix the root cause that led to the shutdown first.
  3. For multi-MCU machines, check the USB IDs or CAN UUIDs for [mcu] and [mcu xxx] one by one.
  4. If Klipper was recently updated, recompile and flash all MCU firmware.
  5. If using [mcu host], check that the klipper-mcu service is running correctly, then restart Klipper.
  6. If using a pre-installed or customized Klipper system, ensure the log is complete and the Klipper and MCU firmware versions are from consistent sources.

MCU 'xxx' shutdown: Command request​

Error Message: MCU 'xxx' shutdown: Command request. Common causes:

  • The CAN toolboard firmware version does not match the host Klipper version, causing the host to send commands unsupported by the firmware.
  • After updating Klipper or the system, the toolboard firmware was not recompiled and flashed.
  • A feature was configured that the MCU firmware was not compiled to support (e.g., configuring EDDY/ADXL without enabling I2C).

Solutions:

  1. Check Loaded MCU 'xxx' ... version and Git version in klippy.log to confirm if the versions match.
  2. Recompile and flash the firmware for the error-reporting MCU. Refer to the corresponding toolboard product documentation for the flashing method.
  3. For multi-MCU machines, ensure all MCU firmware comes from the same compilation.
  4. After flashing, execute FIRMWARE_RESTART and confirm the error no longer appears.

General version troubleshooting: MCU Protocol error

Shutdown due to M112 command / webhooks request​

Error message: Shutdown due to M112 command or Shutdown due to webhooks request.

Solutions:

  1. Confirm whether the emergency stop was triggered manually; if so, after eliminating the risk, execute FIRMWARE_RESTART.
  2. Search for M112, action_emergency_stop, emergency_stop in custom macros.
  3. Check if the frontend, remote control plugins, or automation scripts have accidentally triggered the emergency stop interface.

Insufficient host performance causing print stuttering​

Error message: No clear error, but intermittent pauses and extrusion inconsistencies occur during printing.

Solutions:

  1. Reduce print speed and acceleration.
  2. Close unnecessary web services, camera streams, etc., on the host.
  3. Reduce probe_count and mesh_pps in [bed_mesh].
  4. If the slicer outputs G2/G3 arcs, refer to Arc fitting recommendations to adjust or disable them.
  5. If the host performance is genuinely insufficient, consider replacing it with a more powerful one.

Host abnormal restart / System crash​

Error message: Klipper/Moonraker suddenly disconnects during printing, klippy.log ends abruptly without a clear shutdown root cause; after Mainsail/Fluidd reconnects, the host or Klipper has restarted.

Common causes:

  • Insufficient power supply to the host; load changes from USB, camera, screen, or fans during printing cause a power drop.
  • Abnormal read/write on the system disk, TF card, or eMMC; logs terminate abruptly or files become corrupted.
  • Host CPU overheating, leading to protective throttling, freeze, or restart.
  • Abnormal USB back-powering or peripheral power path, causing mutual interference between the motherboard, screen, or host.
  • Third-party services, camera streams, AI plugins, or excessive web connections consuming resources.

Troubleshooting methods:

Power off operation

Before checking the host power cable, USB cable, screen cable, fan cable, or routing wires, completely turn off the printer and disconnect the power supply. Do not disassemble the power supply or modify mains wiring.

  1. First, check klippy.log, moonraker.log, and system logs to confirm whether it's a Klipper error or a full host restart.
  2. Check the host's power supply specifications; avoid using cables with insufficient current or obvious voltage drop.
  3. Check the health of the system disk; replace the SD card, eMMC, or reflash the system if necessary.
  4. Check host cooling; ensure the fan is working, heat sinks are properly attached, and the case has ventilation.
  5. Temporarily disable camera streams, KlipperScreen, remote control plugins, and other high-load services, then test print again.
  6. If USB back-powering is suspected, prioritize using a quality USB cable or a connection scheme with power isolation; ordinary users should not attempt to modify wiring themselves.

Pause, Resume, and State Save Prompts​

Error message: Print already paused, Print is not paused, resume aborted, Unknown g-code state: PAUSE_STATE.

Common causes:

  • Executing PAUSE repeatedly, or executing RESUME after the print has already been cancelled.
  • Mismatched names between SAVE_GCODE_STATE NAME= and RESTORE_GCODE_STATE NAME= in custom pause/resume macros.
  • Redefined or conflicting logic between third-party macro packages and the default pause/resume macros in Mainsail/Fluidd.
  • After an emergency stop, FIRMWARE_RESTART, or Klipper error, the original pause state is lost.

Solutions:

  1. Confirm the current print status; do not execute RESUME when not paused.
  2. Check if [pause_resume] is enabled, and if the PAUSE/RESUME/CANCEL_PRINT macros are redefined.
  3. Verify if the names in SAVE_GCODE_STATE and RESTORE_GCODE_STATE macros are exactly the same.
  4. After a Klipper error or emergency stop, it is not recommended to attempt resuming the print; eliminate the risk and start a new print.

Klipper Repeating Restart Loop (Klippy not connected flashing repeatedly)​

Error message: Mainsail/Fluidd shows Klippy not connected repeatedly. Klipper restarts itself constantly, exiting within seconds each time. The log may show Klipper restarting too fast or each restart's klippy.log is very short.

Troubleshooting methods:

  1. First, check the end of the log file to confirm the reason for the last exit:

    tail -100 ~/printer_data/logs/klippy.log

  2. If the end of the log is a Python Traceback, it indicates a crash caused by config parsing or an internal exception.

  3. Do not rely solely on Klipper restarting too fast for the root cause; it is often just the result of systemd repeatedly failing to launch Klipper. Prioritize handling the first real error in klippy.log.

  4. If the log shows MCU Protocol error, Unknown command, etc., it means the firmware version is mismatched; recompile and flash the MCU firmware.

  5. If the log is very short with no clear error, try a binary search method using a minimal configuration.

  6. Check for circular includes in include files.

Unhandled exception during run​

Error message: Unhandled exception during run, the frontend shows Printer is shutdown, with a Python Traceback in the log.

Common causes:

  • This is not an independent hardware fault, but a generic error after Klipper's main loop catches an unhandled exception. The real cause requires looking at the specific error above the Traceback.
  • Common triggers: TMC UART read failure (Unable to read tmc uart 'stepper_x' register DRV_STATUS), CAN communication interruption, macro template runtime errors, third-party module exceptions.
  • After upgrading Klipper, old configurations or macros are incompatible with the new API version.
  • Corrupted Python environment or missing dependencies on the host.

Solutions:

  1. Open the full klippy.log, search for the Traceback above Unhandled exception during run, and find the first real error (e.g., Unable to read tmc uart, CanError, TypeError).
  2. If the real error is TMC UART communication failure, check wiring and configuration according to TMC Error Troubleshooting.
  3. If it's a CAN communication anomaly, check the bus status according to CAN Error Troubleshooting.
  4. If the Traceback points to a macro or extension module, check if the module is compatible with the current Klipper version; update or temporarily disable it if necessary.
  5. If this error appears after upgrading Klipper, check Config_Changes.md for any configuration migration requirements.
  6. Do not diagnose the problem based solely on the Unhandled exception during run line; it is only an envelope; the real cause is always found in the Traceback.

Missed scheduling of next hard pwm event​

Error message: MCU 'mcu' shutdown: Missed scheduling of next hard pwm event.

Common causes:

  • Similar to Missed scheduling of next digital out event, it means the host failed to send the PWM event to the MCU within the deadline.
  • High host CPU load (camera stream, KlipperScreen, many plugins running simultaneously).
  • When using laser modules or high-frequency PWM tools, cycle_time is set too small, resulting in extremely short scheduling intervals.
  • CAN bus latency is too high, causing the event to time out during transmission.

Solutions:

  1. Check host CPU load; temporarily disable cameras, KlipperScreen, and other non-essential services, then retest.
  2. If using a laser or PWM tool, appropriately increase cycle_time (e.g., change from 0.00002 to 0.0001).
  3. Check the CAN bus status; confirm that tx_error and bytes_retransmit are not continuously increasing.
  4. Try using a higher quality USB cable or lowering the CAN baud rate (e.g., from 1M to 500K).
  5. For low-performance hosts (old phones, low-end development boards), it is recommended to reduce the number of concurrently running services.

Related error: Missed scheduling of next digital out event

Can't reset time when stepper active​

Error message: MCU 'mcu' shutdown: Can't reset time when stepper active, often accompanied by Klipper automatically restarting during a print; after restart, TMC stepper_x failed to init: Timeout on wait for 'tmcuart_response' response may appear.

Common causes:

  • This is not an independent hardware failure, but rather the host attempting to reset the stepper clock reference while the stepper motor is still moving; the MCU refuses and enters shutdown protection.
  • The most common trigger is Klipper service spontaneously restarting during a print (on the host side): the log will show Starting Klippy... immediately after a Stats line from printing seconds earlier.
  • A client or plugin connected via Moonraker repeatedly requests a service restart.
  • Insufficient power, overheating, or memory exhaustion on the host causes the system to kill and relaunch the Klipper service.

Solutions:

  1. Open the complete klippy.log, search for Starting Klippy..., confirm whether Klipper restarted mid-print, and check the time interval from the last print statistics line.
  2. Run systemctl status klipper.service and journalctl -efu klipper to view records and reasons for service restarts.
  3. Check clients and plugins connected via Moonraker (camera streams, third-party plugins, custom scripts) to ensure no device is requesting service or machine restarts.
  4. Check host power supply, cooling, and memory usage. Older Raspberry Pi models or low-performance development boards running both a camera and KlipperScreen are prone to being killed by the system due to insufficient memory.
  5. The Timeout on wait for 'tmcuart_response' appearing after a restart is a consequence of the restart, not the root cause; do not prioritize checking TMC wiring.

Related errors: Klipper repeated restarts, Unhandled exception during run

Loading...