How-To Trouble-Shoot

How-To Trouble-Shoot

Following is a collection of general trouble-shooting tips. These should be followed before posting a request for help

  1. Basic Trouble-Shooting
  2. Connection Problems to the printer board
  3. Works when cold but stops working when hot or moving


  • Around 50% of the typical issues are due to the points discussed in the following
  • Another 49.8% are configuration issues
  • The last 0.2% might either be bugs or are just designed as is

Basic Trouble-Shooting

  1. Check your wiring / jumper settings against the printer board specification. Often the schematic and pin-out diagrams can be found on GitHub. Some examples:
    • BIGTREETECH: Name of the board → hardware → xxx_PIN.pdf / xxx_SCH.pdf
    • Makerbase: Name of the board → hardware → xxx_PIN.pdf / xxx_SCH.pdf
    • FYSETC
  2. Physically check the wiring
    • Are all connectors properly seated?
    • Any cables damaged / frayed (often they break in the connector)?
  3. Start with a “bare metal” printer.cfg. This will help to exclude external contributors and make it easier for the supporting people here to spot issues. Work from ground up
    • Use an official config from Klipper or a known good sources like Voron etc.
    • Remove macros that are not needed for basic operation (we see a lot configs where basic operation has never worked but contains a mile long additional macros of unknown sources / quality)
    • Remove webcam / display
  4. Take extra caution to have followed the official installation procedure
    • In doubt repeat it again
    • Closely watch the output of each step. There must be no error messages (they sometimes “hide” a few lines up)
  5. Consult the klippy.log file
    • Typically found either under /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. Often this message already contains helpful hints. If you have found an error message refer to the collection of common error messages to get further ideas on how to solve them.
    • If you see the dirty notification in the log, then your Klipper installation contains unknown modifications. Remove them / take care to install a pristine 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 attached to TMC driver A but not when attached to TMC driver B
    • Try if the entire system starts working when removing, e.g. a BLtouch, MAX31865 board or ADXL345 etc
    • One faulty component can cause multiple other components to fail, especially when connected, for example, to the same SPI bus on the printer board

Connection Problems to the printer board

If the above steps have been followed, but Klipper is still not able to connect to the printer board then these steps might help

  1. Execute ls /dev/serial/by-id/*
    • The result must look similar to /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0
    • If not check your USB connection / cable
  2. Repeat flashing the printer board’s firmware
    • Take extra caution to closely follow the instructions on top of the official config files during the make menuconfig process
    • Also note any instructions there on how to flash the firmware to the board. Often small details need to be observed like not using the same filename twice
    • If using the make flash FLASH_DEVICE=... command, closely watch its output for error messages
  3. Check Linux Diagnostic Messages
    • Unplug the printer board from your SBC’s USB
    • Replug the printer board to the SBC
    • Execute sudo dmesg -e
      A properly flashed board should look like:
    [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
    • A FIRMWARE_RESTART will also cause this block to appear in dmesg
    • If the dmesg output shows the above block without a FIRMWARE_RESTART repeatedly or you have failed prints and such messages, then this points to an unstable connection between the SBC and your printer-board
    • Scroll through the entire output of dmesg. Any other error messages (often printed in red), especially the ones relating to USB, may be a big time contributor to an unstable / non-working Klipper installation

Works when cold but stops working when hot or moving

If problems only occur when the printer is hot and / or moving then following pointers may help

  • Especially wiring issues, e.g. pre-damged cables, flaky connectors etc. might dominantly show up when subject to movement or heat
  • Heating cartridges may fail when getting hot
  • Especially with high bed and nozzle temperatures the used power supply might be too weak. Reduce the load by setting a lower temperature. If the problem vanishes, then it is a strong indication for this type of issue