How-To Trouble-Shoot

How-To Troubleshooting

The following is a collection of general troubleshooting tips. These should be followed before posting a Request for Help

  1. Basic Troubleshooting
  2. Connection Problems to the Printer Board
  3. Linux dmesg
  4. Works when cold, but stops working when hot or moving


  • Approximately 50% of typical problems are due to the items discussed below.
  • Another 49.8% are configuration problems
  • The last 0.2% could be either bugs or are just designed as is.

Basic Troubleshooting

  1. Check your wiring / jumper settings against the printer board specification. Often the schematics and pinouts can be found on GitHub. Some examples:
    • BIGTREETECH: Board name → Hardware → xxx_PIN.pdf / xxx_SCH.pdf
    • Makerbase: Board name → Hardware → xxx_PIN.pdf / xxx_SCH.pdf
    • FYSETC
  2. Physically check the wiring
    • Are all connectors properly seated?
    • Are any cables damaged / frayed (often they break in the connector)?
  3. Start with a “bare metal” printer.cfg. This will help exclude outside contributors and make it easier for the support people here to spot problems. Work from the ground up
    • Use an official config from Klipper or a known good source like Voron etc.
    • Remove macros that are not needed for basic operation (we see a lot of configs where basic operation has never worked, but contains a mile of additional macros from unknown sources/quality).
    • Remove webcams / displays
  4. Take extra care to have followed the official installation procedure
    • If in doubt, do it again
    • Carefully watch the output of each step. There should be no error messages (they sometimes “hide” a few lines above).
  5. Consult the klippy.log file
    • Typically found in either /tmp/klippy.log or ~/printer_data/logs/klippy.log.
    • Start at the bottom and scroll up until you find something that looks like an error message. This message often contains helpful hints. Once you have found an error message, see the collection of common error messages for more ideas on how to fix it.
    • If you see the message dirty in the log, your Klipper installation contains unknown modifications. Remove them / make sure you install a clean Klipper from the official source.
  6. Exclude faulty hardware
    • Try if a component, e.g. stepper, works in slot A but not in slot B
    • Try if a component, e.g. stepper, works when connected to TMC driver A, but not when connected to TMC driver B
    • Check if the whole system works when removing e.g. a BLtouch, MAX31865 board or ADXL345 etc.
    • One faulty component can cause several other components to fail, especially if they are connected to the same SPI bus on the printer board, for example.

Connection Problems to the Printer Board

If the above steps have been followed and Klipper is still unable to connect to the printer board, the following steps may help

  1. Run ls /dev/serial/by-id/*.
    • The result should look similar to /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0.
    • If not, check your USB connection/cable and hardware as described above.
  2. Repeat flashing the printer board firmware
    • Take extra care to follow the instructions at the top of the official config files during the make menuconfig process.
    • Also pay attention to any instructions there on how to flash the firmware to the board. Often there are small things to be aware of, like not using the same filename twice.
    • When using the make flash FLASH_DEVICE=... command, watch the output closely for any error messages.
  3. Follow the directions in the next chapter and analyze how the board registers in the Linux operating system

Linux dmesg

The dmesg command presents boot and hardware-related messages from the kernel ring buffer, making it an invaluable tool for identifying Linux issues.
Regarding Klipper, it supplies diagnostic data about the printer board’s connection process and offers hints if that procedure is not functioning properly or is getting disturbed.

:warning: dmesg will print a lot of information. Some of it may be printed in red, which seems to indicate an error. Actually, it may or may not be true: Much of this information is developer related, and even if it is displayed as an error, it may be handled gracefully internally and is not really a problem. The average user can safely ignore most of these messages unless they are trying to diagnose problems.

  1. Turn on the printer so that the printer board is powered up.
  2. Unplug the printer board from the USB port on your SBC/computer.
  3. Reconnect the printer board to the SBC/computer.
  4. Run sudo dmesg -e and analyze the last handful of lines
    • Run sudo dmesg > dmesg.txt and post the ‘dmesg.txt’ file if you need help interpreting the results.

A properly flashed board should look like this

[127913.638806] usb 5-1: new full-speed USB device number 25 using ohci-platform
[127913.873733] usb 5-1: New USB device found, idVendor=1d50, idProduct=614e, bcdDevice= 1.00
[127913.873755] usb 5-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[127913.873761] usb 5-1: Product: lpc1769
[127913.873765] usb 5-1: Manufacturer: Klipper
[127913.873769] usb 5-1: SerialNumber: 0C70001625813AAF86E06B5CC32000F5
[127913.877920] cdc_acm 5-1:1.0: ttyACM0: USB ACM device

The output, where e.g. BRLTTY or the ModemManager has interfered with the board’s connection, would look like:

[  148.243510] usb 1-2: USB disconnect, device number 4
[  161.472108] usb 1-2: new full-speed USB device number 5 using xhci_hcd
[  161.621853] usb 1-2: New USB device found, idVendor=1a86, idProduct=7523, bcdDevice= 2.64
[  161.621873] usb 1-2: New USB device strings: Mfr=0, Product=2, SerialNumber=0
[  161.621881] usb 1-2: Product: USB Serial
[  161.631484] ch341 1-2:1.0: ch341-uart converter detected
[  161.632130] usb 1-2: ch341-uart converter now attached to ttyUSB0
[  162.258424] input: BRLTTY 6.4 Linux Screen Driver Keyboard as /devices/virtual/input/input18
[  162.385361] usb 1-2: usbfs: interface 0 claimed by ch341 while 'brltty' sets config #1
[  162.386054] ch341-uart ttyUSB0: ch341-uart converter now disconnected from ttyUSB0
[  162.386084] ch341 1-2:1.0: device disconnected

To handle such events, please refer to BRLtty / ModemManager - Services Interfering with Klipper

General notes:

  • This block will also appear in dmesg when there’s a FIRMWARE_RESTART.
  • If the dmesg output repeatedly shows this block without a FIRMWARE_RESTART, or if you are experiencing failed prints and messages like this, it indicates an unstable connection between the SBC and your printer board.
  • Scroll through the complete output of dmesg. Additional error messages (which are often printed in red), particularly ones related to USB, may also contribute to a malfunctioning or unstable Klipper installation.

The system works when cold, but ceases to function when it becomes hot or is in motion

If the issues only occur when the printer is hot and/or moving, the following may help:

  • Wiring issues, such as pre-damaged cables and flaky connectors, tend to appear dominantly when subjected to movement or heat.
  • Heating cartridges tend to fail when they get hot.
  • The power supply used may be too weak, particularly when high bed and nozzle temperatures are utilized. Decrease the load by lowering the temperature. If the problem disappears, it is a strong indication of this type of issue.