Skip to main content

System, Performance, and Service Errors

This page organizes issues related to communication timeouts, MCU timing errors, host performance, firmware flashing, and Klipper service startup problems.

Homing Timeout Issues​

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

Common Causes:

  • High host load, with KlipperScreen, camera streams, and other services running simultaneously.
  • During homing, multiple axis motors move simultaneously; high-current drive signals couple into the CAN/USB communication lines, causing communication interruptions.
  • Unstable multi-MCU communication responses.
  • Poor quality CAN/USB communication cables or improper routing.

Solutions:

Power Off Operation

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

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

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

Error Message: The step events that Klipper planned to send to the MCU have fallen behind the current time. The MCU can no longer execute these motion commands at the expected time, and the printer enters a shutdown state.

Loading...

Cause of Error: This is usually not caused by a single fixed configuration item, but rather results from the host-side motion planning, MCU step output, or communication scheduling being unable to keep up. High host load, excessive print speed/acceleration, excessive step subdivision, 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 probing, if the 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 the host's computational and motion planning load. This is just one common scenario; even without bed probing, other situations that increase system load or communication latency may also trigger Stepper too far in past.

Stalled Scenario After Print Recovery: The error may also occur after PAUSE / RESUME, filament runout recovery, or power-loss resume. Typical log manifestations: after recovery, the buffer_time in the Stats line drops sharply from approximately 1s to around 0.2s, sd_pos barely increases (print progress stalls), but sysload is not high and there is no MCU disconnection. This indicates that motion commands are not continuously filling the step buffer after recovery, and the printer "starts printing but barely moves" before entering shutdown. When troubleshooting, focus on checking whether the recovery/resume macros (resume_gcode, start_gcode) send abnormal large movement or retraction commands at the moment of recovery, and whether communication retransmissions (bytes_retransmit growth) already existed before recovery.

Solutions:

  1. First, check the Stats lines before the error in klippy.log to confirm whether there are simultaneously high CPU usage, bytes_retransmit, bytes_invalid, Timer too close, MCU disconnections, or queue anomalies.
  2. Temporarily disable camera streams, KlipperScreen, remote control plugins, and other high-usage services to reduce host load, then retest.
  3. Reduce print speed, acceleration, and step subdivision, and observe whether the error disappears.
  4. If the error occurs during multi-point bed probing, reduce the probe_count in [bed_mesh], for example, change it to 7,7 or 9,9 for testing.
  5. If a high mesh_pps is configured, reduce or remove it, for example, change it to mesh_pps: 2,2.
  6. Check USB/CAN communication quality; if using CAN, confirm queue length, termination resistors, wiring order, power supply, and firmware CAN speed.
  7. Check the macro or G-code being executed before the error is triggered, and avoid macro loops, overly dense short line segments, or abnormal scripts sending a large number of motion commands in a short time.

Related configuration references: Macro Introduction, Common Debug Directives.

MCU 'mcu' shutdown: Timer too close​

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

Loading...

Cause of Error: Excessive load on the lower computer (MCU), host response timeout, excessive print speed, excessive subdivision, system time synchronization interference, or interference on MCU communication lines can all trigger this issue.

Recent Common Scenarios:

  • After M600, PAUSE, RESUME, filament runout detection, or filament change macros wait for a period and then resume printing, Timer too close is subsequently triggered.
  • When EDDY / TAP / CAN tool boards participate in Z homing, Z_TILT_ADJUST, QUAD_GANTRY_LEVEL, or bed probing, the log simultaneously shows CAN retransmissions, abnormal I2C readings, or host load spikes.
  • When multi-toolhead, multi-CAN node, or low-performance host systems run cameras, KlipperScreen, and remote control plugins simultaneously, there is insufficient scheduling margin.

Solutions:

  1. Reduce stepper motor subdivision to decrease MCU pulse processing pressure.
  2. Reduce print speed and acceleration, and observe whether the issue disappears.
  3. Check host load, power supply, and USB/CAN communication quality.
  4. After powering off, check whether the communication lines between the MCU and host are routed near motor wires, heater wires, heated bed wires, or power wires. If necessary, reroute or replace with shielded communication cables.
  5. When checking machine grounding, only confirm the grounding point provided by the manufacturer and the outlet status. Do not disassemble the power supply or modify the mains ground wire on your own.
  6. If the issue occurs during the homing phase, refer to Homing Timeout Issues.
  7. If it occurs after M600 or filament runout recovery, check whether PAUSE is repeated in the macro, whether the filament runout sensor is falsely triggered during the filament change process, and whether the SAVE_GCODE_STATE / RESTORE_GCODE_STATE names are consistent.
  8. If it occurs during EDDY TAP, Z tilt, or gantry leveling, first refer to EDDY TAP Mode Debugging Method, or troubleshoot according to EDDY Issue Collection.
  9. If the issue persists, consider reflashing the host system or firmware.

Related configuration references: 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 of Error: After the Klipper host turns on digital outputs such as heaters or fans, 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, and the MCU does not receive the next digital output event in time, it will enter a shutdown state.

Note

This error is related to heater output scheduling. Do not bypass the error by disabling temperature protection, disabling verify_heater, or removing safety configurations. First, troubleshoot host load and communication quality.

Solutions:

  1. First, check the Stats lines before this error in klippy.log to confirm whether bytes_retransmit, bytes_invalid, Timer too close, or MCU disconnection records exist simultaneously.
  2. Reduce host load by temporarily disabling camera streams, KlipperScreen, remote control plugins, or other high-usage services.
  3. Check USB/CAN communication quality; if using CAN, confirm CAN0 queue length, termination resistors, wiring order, power supply, and firmware CAN speed.
  4. Reduce print speed, acceleration, and step subdivision, and observe whether the issue disappears.
  5. If it only occurs during heating, also check the load on the heated bed, hotend, fans, and power supply; do not disassemble the power supply or inspect mains heated bed high-voltage wiring on your own.
  6. If the issue occurs on a CAN tool board, continue troubleshooting according to CAN Error Troubleshooting.

Related configuration references: 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 of Error: Host system clock issues or excessive CPU load cause timer tasks to actually execute later than the scheduled 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 disabling unnecessary web interfaces or camera streams.
  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 see if the klippy process has abnormal CPU usage. For related configuration, refer to: Common Debugging Directives.

MCU 'mcu' shutdown: Move queue overflow​

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

Cause: The MCU motion queue has been filled, and the host has not synced motion planning and status to the MCU in time. This is commonly seen with insufficient host performance, a large number of small movements in a short period, version mismatch between the Klipper host and MCU firmware, or vendor-customized Klipper that adds blocking logic such as synchronous disk writes or power-loss resume to every movement command.

Common diagnostic points:

  • In klippy.log, there is a significant gap between the Git version and the Loaded MCU 'xxx' ... version base version.
  • The log shows dirty, third-party klippy/extras files, vendor-customized power-loss resume, or unofficial Klipper.
  • The same G-code file fails at a similar location, and the model contains a large number of short line segments, dense supports, spiral Z-hop, or complex paths.
  • A low-performance host is simultaneously running a camera, screen, remote control, or other high-load services.

Solutions:

  1. Check the full klippy.log first to confirm whether there are any earlier Timer too close, CAN disconnection, bytes_invalid, or temperature/TMC errors.
  2. After updating Klipper, recompile and flash all MCU firmware to ensure the host, mainboard, and toolboard firmware versions match.
  3. Temporarily disable the camera stream, KlipperScreen, remote control plugins, and other high-usage services, then retest.
  4. Lower print speed, acceleration, and microstepping, or reduce curve precision, support complexity, and short line segment density in the slicer.
  5. If using vendor-customized power-loss resume, automatic height recording, or third-party plugins, first cross-test with original Klipper or by disabling the corresponding feature; do not directly modify Klipper source code as a routine step for regular users.
  6. If this only occurs with a specific G-code file, re-slice and check whether the slicer is outputting abnormally dense paths.

For related configuration, refer to: Common Debugging Directives, Arc Fitting Recommendations.

stepcompress / syncemitter / flush_handler Internal Errors​

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 encountered an internal exception while generating or compressing stepper pulses. In recent community cases, this type of issue often co-occurs with 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 re-slicing alone should not be used to determine the root cause.

Solutions:

  1. Keep the full klippy.log and focus on the Python Traceback, the command being executed, and the Stats lines immediately before and after the error.
  2. If the error occurs during BED_MESH_CALIBRATE, QUAD_GANTRY_LEVEL, or scanner probing, first reduce the probing speed, point count, interpolation density, and plugin scan parameters.
  3. Temporarily disable third-party scanners, automatic speed adjustment, enhanced auto-leveling, macro packages, or vendor modifications, and retest with original Klipper.
  4. After updating Klipper, reflash all MCU firmware and confirm the peripheral firmware matches the host Klipper version.
  5. If the same model triggers this repeatedly, re-slice and reduce short line segment density; if it still occurs randomly after re-slicing, continue troubleshooting based on host load, motion parameters, and plugin compatibility.
  6. If the printer shows abnormal movement, missed steps, or crash risk, immediately 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 during connect / has no attribute​

Error message: After updating Klipper, startup cannot complete, and the log shows Unhandled exception during connect, Internal error during connect, and the Traceback may end with something like:

AttributeError: 'MCU' object has no attribute '_serialport'

Other has no attribute, got an unexpected keyword argument, or module interface missing messages may also appear.

Nature of the error: This type of error indicates that Klipper encountered an exception while executing Python code during the connection initialization phase. In recent community cases, if the Traceback points to a third-party klippy/extras/ module, it is usually because Klipper has updated internal interfaces while an older extension or vendor-customized module is still calling the old interface; it generally does not indicate MCU firmware corruption, nor should it be treated as a serial port wiring fault first.

Common causes:

  • Klipper has been updated, but third-party probe, filament change, macro package, or other extensions have not been updated accordingly.
  • A vendor-customized Klipper branch is being used, but extensions that only work with original Klipper are mixed in.
  • Extension files were updated incompletely, leaving both old and new Python files behind.
  • The Traceback actually points to other exceptions in config files, variable files, or original modules, rather than an extension compatibility issue.

Solutions:

  1. Save the full klippy.log, read the Traceback downward from the first Unhandled exception during connect, and record the final exception as well as the last klippy/extras/xxx.py file name before the exception.
  2. Check the Git version, Modified files, and Untracked files at the beginning of the log. If the exception file belongs to a third-party extension, first update it to a version compatible with the current Klipper according to that extension's maintenance instructions.
  3. Temporarily disable the third-party module pointed to by the Traceback or its related include, then restart to confirm whether original Klipper can connect properly. Do not repeatedly flash the MCU to resolve a Python attribute error.
  4. If using a vendor-customized Klipper, use the update method explicitly supported by that system; do not arbitrarily mix original Klipper, customized branches, and extensions of different versions.
  5. If the Traceback only points to original Klipper files, and Modified files / Untracked files show no anomalies, update to the current stable version, collect the full log again, and report the reproducible steps to the Klipper community.
  6. Downgrading should only be used for short-term confirmation of whether it is a version compatibility issue. The long-term solution is to update the extension or remove the incompatible module, not to stay on a known outdated version.

Internal error during ready callback: Unable to save variable​

Error message: Klipper enters shutdown immediately after startup, and the log contains the following keywords:

Unable to save variable
reactor.ReactorError: Internal error - reactor pause disabled
Unhandled exception during ready callback
Internal error during ready callback: Unable to save variable

Nature of the error: Unable to save variable is only a result message indicating that variable writing failed. In recent community cases, if it appears together with reactor pause disabled and ready callback, it is usually because a third-party extension is calling SAVE_VARIABLE during Klipper's ready callback phase, which is incompatible with the newer asynchronous write mechanism; this does not equate to storage device damage or MCU disconnection.

Common causes:

  • After updating Klipper, an older third-party extension is still synchronously writing variables in the startup callback.
  • An extension or vendor-customized module has not been updated accordingly, and the Traceback points to its klippy/extras/ file.
  • If the log does not contain reactor pause disabled, it may also be due to an incorrect variable file path, read-only directory, exhausted disk space, or permission issues.

Solutions:

  1. Read the full Python Traceback from the first Unable to save variable in klippy.log, and record the first third-party module path and the original exception text; do not only look at the final shutdown line.
  2. If reactor pause disabled and a third-party extension path appear together, first update that extension to a version compatible with the current Klipper, then restart Klipper; if no compatible version exists, contact the extension maintainer.
  3. Temporarily disable the third-party extension pointed to by the Traceback or its related include and retest to confirm whether original Klipper can start normally. Do not directly modify Klipper core source code as a routine troubleshooting step.
  4. If the Traceback indicates Permission denied, Read-only file system, or No space left on device, run the following commands to check disk space and variable file permissions, then correct the actual path or permissions; do not use chmod 777 to broaden permissions on unrelated directories.
df -h
ls -l ~/printer_data/config/
  1. Downgrading Klipper should only be used for short-term compatibility verification and should not be used as a long-term solution; after confirming the issue, restore the supported Klipper version and update the corresponding extensions.

Internal error on command​

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

Common causes:

  • A macro or G-code command triggered an internal Python exception in Klipper.
  • There are incorrect macro references or Jinja2 template syntax errors in the configuration file.
  • The Klipper version is incompatible with the configuration file format.
  • G-code file names contain special characters causing encoding errors.
  • stepcompress, syncemitter, or flush_handler errors interrupted command execution.

Solutions:

  1. Check the full Python Traceback below the Internal error in klippy.log.
  2. Use the Traceback to identify which configuration file or macro is causing the problem.
  3. Common causes include Jinja2 template syntax errors in [gcode_macro], missing [respond] configuration, and incorrect [virtual_sdcard] paths.
  4. If the error is related to SDCARD_PRINT_FILE and indicates ascii codec can't decode, change the G-code file name to use English letters, numbers, underscores, or hyphens.
  5. If stepcompress, syncemitter, or flush_handler appears in the Traceback, continue troubleshooting by referring to stepcompress / syncemitter / flush_handler internal errors.

Related configuration references: Macro introduction, Configuration modification instructions.

Unable to open file / SD busy​

Error message: When printing a file, Unable to open file, Unable to get file list, SD busy, SD write not supported, or SDCARD_RESET_FILE cannot be run from the sdcard is displayed.

Common causes:

  • The G-code file does not exist, the file name has been changed, or the upload was not completed.
  • [virtual_sdcard] path points to the wrong directory.
  • File permission anomalies prevent the Klipper user from reading the file.
  • The file name contains special characters, causing abnormal path handling in certain frontends or systems.
  • While printing or reading a file, commands to open, select, reset, or write to the virtual SD are also being executed.
  • The Klipper source code directory, configuration directory, or other non-G-code directories are incorrectly set as [virtual_sdcard] path.

Solutions:

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

Related configuration references: Configuration modification instructions.

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

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

Key diagnostic point: Can not update MCU 'xxx' config as it is shutdown is usually not the root cause but a subsequent error that appears when Klipper tries to reconnect or reconfigure the MCU after it has already entered a shutdown/error state. When troubleshooting, do not only look at the last line of the log; scroll up to find the earlier first real error.

Solutions:

  1. Execute FIRMWARE_RESTART, and if necessary, power off the entire machine for 10 seconds before powering it back on.
  2. Check the earlier first shutdown, Timer too close, Lost communication, Verify heater, TMC, or temperature error in klippy.log, and first fix the root cause that led to the shutdown.
  3. For multi-MCU machines, check the USB IDs or CAN UUIDs of [mcu] and [mcu xxx] one by one.
  4. If Klipper was recently updated, recompile and flash the firmware for all MCUs.
  5. If using [mcu host], check whether the klipper-mcu service started normally, then restart Klipper.
  6. If using a preinstalled or customized Klipper system, confirm the log is complete and that the Klipper and MCU firmware versions come from consistent sources.

MCU 'xxx' shutdown: Command request​

Error message: MCU 'xxx' shutdown: Command request.

Common causes:

  • The CAN toolhead board firmware version does not match the host Klipper version, and the host sent a command not supported by that firmware.
  • After updating Klipper or the system, the toolhead board firmware was not recompiled and reflashed.
  • Functionality not compiled into the MCU firmware is configured (e.g., configuring EDDY / ADXL without enabling I2C).

Solutions:

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

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 manually triggered; if so, after eliminating the risk, execute FIRMWARE_RESTART.
  2. Search for M112, action_emergency_stop, and emergency_stop in custom macros.
  3. Check whether the frontend, remote control plugins, or automation scripts accidentally triggered the emergency stop interface.

Insufficient host performance causing print stuttering​

Error message: No obvious error, but intermittent pauses and discontinuous extrusion occur during printing.

Solutions:

  1. Reduce print speed and acceleration.
  2. Turn off 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 arc commands, refer to the arc fitting recommendations to adjust or disable them.
  5. If host performance is truly insufficient, consider replacing it with a more powerful host.

Host abnormal restart / system crash​

Error message: Klipper / Moonraker suddenly disconnects during printing, klippy.log suddenly stops without a clear shutdown root cause; after Mainsail / Fluidd reconnects, the host or Klipper is found to have restarted.

Common causes:

  • Insufficient host power supply; load changes from USB, camera, screen, or fans during printing cause a power failure.
  • Abnormal read/write on the system drive, TF card, or eMMC; the log stops suddenly or files become corrupted.
  • Host CPU overheating, causing protective frequency reduction, freezing, or restart.
  • USB reverse power supply or abnormal peripheral power paths, causing the motherboard, screen, or host to interfere with each other.
  • 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 cables, screen cables, fan cables, or reorganizing wiring, 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 this was a Klipper error or a full host restart.
  2. Check the host power supply specifications and avoid power cables with insufficient current or obvious voltage drop.
  3. Check the health of the system drive and replace the TF card, eMMC, or reflash the system if necessary.
  4. Check host cooling to confirm the fan is working, the heatsink is properly seated, and the enclosure has adequate ventilation.
  5. Temporarily disable camera streams, KlipperScreen, remote control plugins, and other high-load services before printing to test.
  6. If USB reverse power supply is suspected, prioritize replacing with a ready-made USB cable or using a connection solution with power isolation; ordinary users should not modify cabling themselves.

Pause, resume, and state saving prompts​

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

Common causes:

  • PAUSE is executed repeatedly, or RESUME is executed after the print has already been canceled.
  • The SAVE_GCODE_STATE NAME= and RESTORE_GCODE_STATE NAME= names do not match in custom pause/resume macros.
  • Third-party macro packages conflict with or duplicate the definitions of the default pause/resume macros in Mainsail / Fluidd.
  • After an emergency stop, FIRMWARE_RESTART, or a Klipper error, the original pause state has already been lost. Solution:
  1. Confirm the current printing status; do not execute RESUME when not paused.
  2. Check whether [pause_resume] is enabled, and whether the PAUSE / RESUME / CANCEL_PRINT macros are defined more than once.
  3. Verify that the SAVE_GCODE_STATE and RESTORE_GCODE_STATE names in the macros are exactly consistent.
  4. After Klipper has reported an error or performed an emergency stop, it is not recommended to resume printing; eliminate the risk and start over.

Klipper repeatedly restarts (Klippy not connected flashing repeatedly)​

Error message: Mainsail / Fluidd shows Klippy not connected appearing repeatedly; Klipper keeps auto-restarting and exits within a few seconds each time. The log may show Klipper restarting too fast, or each restart's klippy.log is very short.

Troubleshooting steps:

  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 shows a Python Traceback, it indicates a crash caused by a configuration parsing error or internal exception.

  3. Do not judge the root cause based solely on Klipper restarting too fast; it is usually just the result of systemd repeatedly failing to start the service. Prioritize the first real error in klippy.log.

  4. If the end of the log shows MCU Protocol error, Unknown command, etc., the firmware version does not match; recompile and flash the MCU firmware.

  5. If the log is very short with no obvious error, try locating the issue using the minimal configuration bisection method.

  6. Check whether include files contain circular references.

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 a standalone hardware fault, but a generic error reported when the Klipper main loop catches an unhandled exception. The real cause needs to be identified from 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, or exceptions from third-party extension modules.
  • After upgrading Klipper, old configurations or macros may be incompatible with the new version's API.
  • The host's Python environment is corrupted or missing dependencies.

Solution:

  1. Open the full klippy.log, search for the Traceback above Unhandled exception during run, and find the first real error (such as Unable to read tmc uart, CanError, TypeError, etc.).
  2. If the real error is a TMC UART communication failure, check the wiring and configuration according to TMC error troubleshooting.
  3. If it is a CAN communication exception, check the bus status according to CAN error troubleshooting.
  4. If the Traceback points to a macro or extension module, check whether that module is compatible with the current Klipper version; update or temporarily disable it if necessary.
  5. If this error occurs after a Klipper upgrade, check Config_Changes.md for any required configuration migration.
  6. Do not judge the problem based solely on the line Unhandled exception during run; it is only the wrapper — the true cause is always in the Traceback.

Missed scheduling of next hard pwm event​

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

Common causes:

  • This is the same category as Missed scheduling of next digital out event; both occur when the host fails to deliver the PWM event to the MCU within the deadline.
  • Host CPU load is too high (camera stream, KlipperScreen, many plugins running simultaneously).
  • When using a laser module or high-frequency PWM tool, the 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.

Solution:

  1. Check the host CPU load; temporarily disable the camera, KlipperScreen, and other non-essential services, then retest.
  2. If using a laser or PWM tool, appropriately increase cycle_time (for example, change from 0.00002 to 0.0001).
  3. Check the CAN bus status and confirm that tx_error and bytes_retransmit are not continuously increasing.
  4. Try replacing with a high-quality USB cable or lowering the CAN baud rate (from 1M to 500K) for testing.
  5. For low-performance hosts (old phones, low-end development boards), it is recommended to reduce the number of simultaneously 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 auto-restarting mid-print; after the restart, TMC stepper_x failed to init: Timeout on wait for 'tmcuart_response' response may follow.

Common causes:

  • This is not a standalone hardware fault, but occurs when the host attempts to reset the stepper clock reference while the stepper motors are still moving; the MCU rejects it and enters shutdown protection.
  • The most common trigger is the Klipper service self-restarting mid-print (host-side): the log will show Starting Klippy... immediately after the Stats lines from the previous second of printing.
  • A client or plugin connected via Moonraker repeatedly requests a service restart.
  • Insufficient host power, overheating, or memory exhaustion causes the system to kill and restart the Klipper service.

Solution:

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

Related errors: Klipper repeatedly restarts, Unhandled exception during run

Loading...