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...

7. Check if uart_address matches the hardware jumper settings on the driver board.
8. 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.

Driver Reset (Reset)

Error Message: TMC 'stepper_x' reports error: GSTAT: 00000001 reset=1(Reset).

Loading...

Error Cause: Unstable power supply or external interference causing the driver to auto-reset. Commonly caused by power voltage fluctuations, poor wiring contact, or electromagnetic interference.

Solution:

1. After completely powering off, check if the 24V power cable, driver module, and motherboard socket are loose, blackened, or burnt.
2. Replace with a known-good power supply, driver module, or cable harness for cross-testing.
3. Check if the driver heatsink and fan are functioning normally.
4. Check if the motor cables run parallel to heater or heated bed cables over long distances. Re-route cabling after powering off if necessary.
5. Power off before operating. Check the motor cable for breaks, internal strand fractures, or intermittent connection issues caused by poor terminal contact. Cables in cable chains may develop fatigue fractures due to long-term movement. Pay special attention to chain bending points and terminal crimping areas.
6. It is not recommended for customers to modify the driver power input, add electronic components, or alter grounding themselves. Such operations should be handled by professionals or after-sales support.

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.