Skip to main content

TMC Error Troubleshooting

Technical Background​

TMC (Trinamic) drivers report status and error information through dedicated registers. Understanding these registers helps with quick issue diagnosis:

  • IFCNT Register: Communication frame counter, used to verify normal communication between the main controller and the driver.
  • GSTAT Register: Global status register, containing global status information such as reset and driver errors.
  • DRV_STATUS Register: Driver status register, providing detailed driver operating status, including temperature warnings, short circuits, open circuits, and other fault information.

When Klipper reports a TMC error, it typically displays specific register values and fault flags. A TMC driver error indicates that the driver chip has detected a problem and has self-protectively disabled itself. Klipper will enter a shutdown state upon detecting a disabled driver.

Power Off Operations

Before checking jumper caps, driver modules, motor cables, SPI/UART wiring order, or terminal blocks, completely turn off the printer and disconnect the power supply. Do not hot-plug driver modules or stepper motor cables. The multimeter resistance mode can only be used when the power is off.

Driver Connection Failure (IFCNT Communication Failure)​

Error Message: Unable to read tmc uart 'stepper_x' register IFCNT or Unable to read tmc spi 'stepper_x' register IFCNT.

Loading...

Error Cause: Communication between the TMC driver (UART/SPI mode) and the main controller has failed, preventing the reading of the IFCNT register value. Common causes include uninstalled UART jumper caps, abnormal driver board power supply, or incorrect UART/SPI pin configuration.

Solution:

  1. After powering off, check if the UART jumper cap for the corresponding driver is correctly installed.
  2. Verify that the uart_pin (or spi_bus / spi_software_*_pin) in the printer.cfg TMC configuration matches the actual wiring.
  3. First, check the power status preliminarily using the power indicator light and the driver module installation orientation. If the indicator is normal, the module orientation is correct, but the issue persists, try using a pre-made cable harness for replacement or cross-testing (move the driver to another port to verify). For electrical testing of exposed 24V terminals, please contact after-sales support or a professional.
  4. If the error occurs immediately after flashing Klipper for the first time, disconnect the entire printer power for a few seconds (unplug both USB and main power), then power on again to clear residual driver status.
  5. After powering off, try replacing the driver board or switching the driver port for testing.
  6. If using a non-FLY brand driver, confirm its UART pin definition (the FLY driver UART pin is usually the fourth pin from the top on the left side).
Loading...

For special cases where the purchased driver's UART pin is on the fifth pin, the following jumper method can be used:

Loading...
  1. Check if uart_address matches the hardware jumper settings on the driver board.
  2. Check if the data cable is intact, without breaks or poor contact.

Driver Overheating (OvertempError / OvertempWarning)​

Error Message: TMC 'stepper_x' reports error: DRV_STATUS: ... ot=1(OvertempError!) or otpw=1(OvertempWarning!).

Loading...

Error Cause: The TMC driver chip temperature has exceeded the safety threshold, triggering protection. Note: This is driver overheating, not motor overheating!

  • OvertempWarning (otpw): Temperature exceeds the ~120°C warning threshold. The driver can still operate, but investigation is recommended.
  • OvertempError (ot): Temperature exceeds the ~150°C shutdown threshold. The driver is automatically disabled.

Solution:

  1. Reduce the motor running current (run_current). It is recommended to start by reducing it by 20-30%.
  2. If a holding current (hold_current) is set, reduce it appropriately or disable it entirely.
  3. Check if the driver heatsink is making good contact and if there is sufficient thermal paste.
  4. Add a cooling fan for the driver to ensure air circulation.
  5. Confirm that the sense resistor value configured on the driver board is correct.
  6. Reduce stealthchop_threshold or switch to spreadCycle mode.
  7. Check if the driver installation environment is sealed, causing heat buildup, and avoid running for extended periods in high-temperature environments.

Short Circuit Fault (ShortToGND / ShortToSupply)​

Error Message: TMC 'stepper_x' reports error: DRV_STATUS: ... s2vsa=1(ShortToSupply_A!) or s2ga=1(ShortToGND_A!).

Error Cause: The driver has detected extremely high current. This can be caused by loose motor wires, a short circuit, damaged motor winding insulation, or overcurrent due to inaccurate load prediction in stealthChop mode.

Solution:

  1. Power off before operating. Check if the corresponding motor wires are loose or damaged. Use a multimeter in resistance mode to measure the motor coil resistance (normally 1.53Ω).
  2. After powering off, check if the motor connector is secure.
  3. If motor case grounding is required, use the grounding point provided by the manufacturer or contact after-sales support. Do not modify the power ground wire or exposed terminals yourself.
  4. Try disabling stealthChop for testing: SET_TMC_FIELD STEPPER=stepper_x FIELD=en_spreadCycle VALUE=1
  5. If the error disappears after switching, it indicates a stealthChop prediction issue; otherwise, it is likely a real hardware short circuit.

Open Load Fault (OpenLoad)​

Error Message: TMC 'stepper_x' reports error: DRV_STATUS: ... ola=1(OpenLoad_A!) or olb=1(OpenLoad_B!).

Error Cause: The driver detects that a phase of the motor winding is not forming an effective load. This usually indicates a disconnected motor wire, loose connector, incorrect coil wiring, or a false alarm in low current/stealthChop states.

Solution:

  1. After powering off, re-plug the motor cable and ensure the terminal crimp is secure.
  2. Power off before operating. Use a multimeter to measure the resistance of the A and B coil sets. The two sets should be similar and should not show an open circuit.
  3. After powering off, check the motor wiring sequence. Confirm that the two wires for phase A are in one set, and the two wires for phase B are in the other set.
  4. Temporarily disable stealthChop: set stealthchop_threshold: 0 in the configuration for testing.
  5. Test with a slightly higher run_current. If it only occurs at very low currents, it may be a false alarm.
  6. After powering off, replace the motor cable or motor for cross-testing to isolate whether the issue is with the harness, motor, or driver port.

Short Circuit + Open Load Combined Fault (Phase A Short, Phase B Open)​

Error Message: TMC 'extruder' reports error: DRV_STATUS: ... s2vsa=1(ShortToSupply_A!) csactual=31 ola=1(OpenLoad_A!) olb=1(OpenLoad_B!).

Error Cause: The TMC driver fault diagnostic bits indicate hardware issues: s2vsa=1 indicates Phase A short to supply, ola=1 indicates Phase A open load, olb=1 indicates Phase B open load, csactual=31 indicates the current setting may be too high. These faults often appear together, indicating a serious hardware problem with the motor or driver.

Solution:

  1. Power off before operating. Use a multimeter to measure the resistance of the stepper motor's A and B coil sets. They should be consistent (typically 1-2Ω and both sets should have similar values).
  2. After powering off, carefully check the stepper motor cable harness and connectors for looseness, short circuits, or poor contact.
  3. Verify if the current setting for the TMC driver is appropriate. Too high a current can cause these issues.
  4. Try disabling stealthChop mode for testing: set stealthchop_threshold: 0 in the configuration.

Short Circuit + Open Load Combined Fault (Phase B Short, Phase A Open)​

Error Message: TMC 'extruder' reports error: DRV_STATUS: ... s2vsb=1(ShortToSupply_B!) ola=1(OpenLoad_A!) cs_actual=25.

Loading...

Error Cause: The TMC driver fault diagnostic bits indicate: s2vsb=1 indicates Phase B short to supply, ola=1 indicates Phase A open load, cs_actual=25 indicates the current setting. This is usually caused by: motor wiring errors (A/B phases reversed or shorted), motor failure (winding open circuit), or driver board hardware issues.

Solution:

  1. Power off before operating. Use a multimeter to measure the resistance of the stepper motor's A and B coil sets. They should be consistent (normally similar values).
  2. After powering off, confirm the motor wiring sequence is correct, typically left set (Phase A), right set (Phase B).
  3. After powering off, check all connection terminals for tightness, looseness, or poor contact.
  4. If possible, after powering off, connect the motor to another known-good driver port for testing.

TMC Driver GSTAT Error (Undervoltage/Reset)​

Error message: TMC 'xxx' reports GSTAT: 00000005 reset=1(Reset) uv_cp=1(Undervoltage!), followed by TMC 'xxx' reports error: GSTAT: 80000000 (may also be readings such as 40000000 with only the highest bit set).

Meaning: GSTAT is the global status register of the TMC driver; only the lower 3 bits are defined:

  • reset=1 (bit0): The driver has undergone a reset (e.g., automatic reset after power-up or undervoltage power loss).
  • drv_err=1 (bit1): Internal driver error, usually accompanied by specific fault flags in DRV_STATUS.
  • uv_cp=1 (bit2): Charge pump undervoltage, indicating that the motor supply voltage on the driver side (VM, typically 24V) has experienced undervoltage or a momentary interruption, and the driver can no longer operate normally.

High-bit readings such as 80000000 and 40000000 are not new fault codes, but invalid data read back via SPI after the driver has been reset by power loss. The fact that specific flags such as reset and uv_cp can be decoded precisely indicates that SPI communication itself is working properly; the problem lies in the driver power supply chain rather than communication. Only when the readings of each driver remain meaningless garbage (such as randomly changing ffffffff) over a long period is it necessary to check the SPI wiring (see SPI Communication Error).

Common causes:

  • Poor contact in the 24V power chain: loose crimping on power terminals, wire gauge too thin, poor contact in the fuse holder, loose VM distribution terminals inside the mainboard.
  • Insufficient power supply load capacity or momentary voltage drop under load: the instantaneous current is highest when multiple motors are enabled simultaneously (e.g., when multiple Z-axis motors are energized at the same time during G28 homing), which is the moment most likely to trigger undervoltage; even if the power supply appears to have sufficient power (e.g., 600W/24V), priority should still be given to checking the terminals and wiring harness chain.
  • Motor phase wire short circuit or damaged motor wires: a short circuit will momentarily pull down VM, causing multiple drivers on the same power chain to report undervoltage simultaneously.
  • When multiple drivers on the same VM chain (e.g., z/z1/z2/z3) report GSTAT anomalies almost simultaneously, it is basically possible to rule out damage to a single driver, and troubleshooting should focus on the shared power supply chain.

Solution:

Power off before operation

Before checking power terminals, wiring harnesses, fuses, or motor wires, please completely turn off the printer and disconnect the power supply. Do not plug or unplug wiring harnesses or touch terminals while powered on.

  1. After powering off, check the 24V input terminals from the PSU to the mainboard: confirm that the crimping is secure, there is no looseness, and there are no signs of blackening or burning; for mainboards with multiple inputs, confirm that each input is properly connected.
  2. After powering off, check whether the wire gauge of the 24V harness meets the current requirements, and check whether the fuse holder (if any) has good contact and whether the fuse specification is correct.
  3. After powering off, use the resistance/continuity range of a multimeter to check the motor wires and motors: confirm that the motor wires are not damaged, there is no short circuit between phases, and the resistance of the two coil groups A/B is normal and similar (reference value approximately 1~3Ω; actual measurements have errors, and the key criterion is that the two readings are consistent).
  4. Calculate the power supply load capacity: tally the total power of motors, heaters, and heated bed working simultaneously and keep a margin; if the power is sufficient but the issue still recurs, focus on checking the terminals and wiring harness according to steps 1 and 2.
  5. If low-voltage measurement conditions are available, you may power on again and measure the voltage at the mainboard 24V input terminals, and observe whether the voltage drops significantly when multiple motors are enabled simultaneously (e.g., during G28) (reference value: it should remain stable near 24V; actual measurements have errors, and the key criterion is the trend of change). When measuring, do not let the test probes short adjacent pins to avoid causing a secondary short circuit.
  6. Cross-validation: after powering off, swap the motor of the erroring axis to another driver port, or replace it with a known-good motor wiring harness for testing, to distinguish whether the issue is with the wiring harness/motor or the power supply chain.
  7. For further electrical testing of exposed terminals and issues with the power supply itself, please contact after-sales service or a professional. Do not disassemble the power supply yourself.

Related configuration reference:

Machines with multiple Z motors should set run_current separately for each Z-axis driver; appropriately reducing the current can reduce the instantaneous voltage drop when they are enabled simultaneously (the values need to be adjusted according to the actual machine conditions and cannot replace power supply chain troubleshooting):

[tmc5160 stepper_z]
run_current: 1.2

[tmc5160 stepper_z1]
run_current: 1.2

During troubleshooting, you can use DUMP_TMC STEPPER=xxx to read the complete driver registers and confirm the real-time status of GSTAT and DRV_STATUS.

Related sections: For troubleshooting when only the reset flag is present, see Driver Reset; for undervoltage protection in DRV_STATUS, see Undervoltage Protection.

Undervoltage Protection (Undervoltage)​

Error Message: TMC 'stepper_x' reports error: DRV_STATUS: ... uv_cp=1(Undervoltage!).

Error Cause: The driver has detected an undervoltage event on the supply. Usually caused by power supply failure, loose wiring, or insufficient power supply capacity.

Solution:

  1. After completely powering off, check if the power cable, motherboard power connector, and terminals appear loose, blackened, or burnt.
  2. Confirm that the power supply specifications meet the total power demand of the drivers and heaters.
  3. Perform a replacement test using a known-good power supply or cable harness.
  4. For electrical testing of exposed 24V terminals, please contact after-sales support or a professional. Do not handle it yourself.

SPI Communication Error (DRV_STATUS: ffffffff)​

Error Message: Unable to write tmc spi 'stepper_x' register ..., TMC reports error: DRV_STATUS: ffffffff ... or READRSP@RDSEL2: 00000000 ....

Error Cause: Inability to communicate with the TMC driver in SPI mode (tmc2130/tmc5160/tmc2660). Usually caused by incorrect SPI wiring, an unconfigured device on the SPI bus, or TMC driver auto-reset/fault.

Solution:

  1. After powering off, check if the SPI wiring order (MOSI, MISO, SCK, CS) is correct.
  2. If the SPI bus is shared among multiple devices, ensure every device is fully configured in Klipper.
  3. After powering off, test with only one driver connected to the motherboard to rule out interference from shared bus devices.
  4. Confirm the driver power supply is normal. Power off for a few seconds and then power on again if necessary.
  5. If the error is accompanied by reset=1, uv_cp=1, or random ffffffff, prioritize checking the power supply and driver contact.

Isolated Driver Test: To verify if a driver is functioning normally in isolation, please refer to the SPI driver standalone testing method in Peripherals and Driver Testing.

TMC SPI Chain Configuration Error​

Error Message: TMC SPI chain must have same length, TMC SPI chain can not have duplicate position.

Error Cause: When using TMC drivers in an SPI daisy chain, the chain_position, chain_length, or chip select configurations of multiple drivers are inconsistent, preventing Klipper from determining each driver's position in the SPI chain.

Solution:

  1. If the motherboard is not designed for a SPI daisy chain, do not arbitrarily add chain_position and chain_length.
  2. Refer to the manufacturer's configuration template for the motherboard or driver board and confirm that the chain_length for each TMC driver is exactly the same.
  3. Confirm that the chain_position for each driver is unique and not duplicated.
  4. If it is a standard SPI bus with multiple CS chip select structures, configure each driver's cs_pin separately and do not use the SPI chain configuration method.
  5. After saving, execute RESTART, then use DUMP_TMC STEPPER=<stepper> to confirm communication for each driver individually.

Timeout on wait for 'tmcuart_response'​

Error Message: Timeout on wait for 'tmcuart_response' response, possibly accompanied in the log by Unable to read tmc uart 'stepper_x' register DRV_STATUS.

Common Causes:

  • TMC UART wiring has cold solder joints, breaks, or poor contact, especially internal fractures in cables within cable chains after repeated bending.
  • Incorrect uart_pin configuration, or the UART jumper cap on the motherboard is not correctly installed.
  • Insufficient driver power supply or power fluctuations, causing the TMC chip to reset during communication.
  • Address conflicts or excessive bus load when multiple drivers share the same UART bus.
  • The motherboard's UART pin is occupied by another function (e.g., Bluetooth, serial debug).

Solution:

Power Off Operations

Before checking the driver board, UART wiring, or jumper caps, completely turn off the printer and disconnect the power supply.

  1. After powering off, check if the UART wiring for the reported driver is secure and if the cable shows signs of significant bending, damage, or cold solder joints.
  2. Confirm that uart_pin matches the actual wiring on the motherboard, and check if the UART jumper cap on the motherboard is correctly installed.
  3. If multiple drivers share a single UART bus, confirm that the uart_address for each driver is unique and not duplicated.
  4. Check if the driver power supply is normal, especially any 12V/24V conversion modules and fuses.
  5. Try swapping the reported driver with a driver from an adjacent axis to determine if the issue is with the driver, the motherboard socket, or the cable harness.
  6. If the error only occurs during printing but not when idle, check if the cable harness is being pulled during movement.

Relationship with IFCNT Error: Timeout on wait for 'tmcuart_response' and Unable to read tmc uart register IFCNT are essentially the same issue: a UART communication timeout. The former often occurs during printing, while the latter often occurs during the startup initialization phase. The troubleshooting methods are the same. See IFCNT Communication Failure.

Timeout on wait for 'tmcuart_response'​

Error message: Timeout on wait for 'tmcuart_response' response, possibly accompanied in the log by Unable to read tmc uart 'stepper_x' register DRV_STATUS.

Common causes:

  • Cold solder joints, breaks, or poor contact in the TMC UART wiring, especially internal breaks in wires inside the drag chain after repeated bending.
  • Incorrect uart_pin configuration, or UART jumpers on the mainboard not properly installed.
  • Insufficient driver power supply or power fluctuations, causing the TMC chip to reset at the moment of communication.
  • Address conflicts or excessive bus load when multiple drivers share the same UART bus.
  • Mainboard UART pins occupied by other functions (such as Bluetooth or serial debugging).

Solutions:

Power off before operation

Before checking the driver board, UART wiring, or jumpers, please completely shut down the printer and disconnect the power supply.

  1. After powering off, check whether the UART wiring of the driver reporting the error is secure, and whether the wires show obvious bending, damage, or cold solder joints.
  2. Confirm that uart_pin matches the actual wiring on the mainboard, and check whether the UART jumpers on the mainboard are properly installed.
  3. If multiple drivers share one UART bus, confirm that each driver's uart_address is unique.
  4. Check whether the driver power supply is normal, especially the 12V/24V conversion module and fuses.
  5. Try swapping the position of the driver reporting the error with an adjacent axis driver to determine whether the problem is with the driver or with the mainboard slot/wiring harness.
  6. If the issue occurs only during printing but is normal when idle, check whether the wiring harness is being pulled during movement.

Relationship to the IFCNT error: Timeout on wait for 'tmcuart_response' and Unable to read tmc uart register IFCNT are essentially the same, both being UART communication timeouts. The former mostly occurs during printing, while the latter mostly occurs during startup initialization. The troubleshooting methods are the same; see IFCNT communication failure for details.

Loading...