Skip to main content

Temperature, Heating, and Extrusion Errors

This page organizes errors related to temperature sensors, heaters, heat beds, extrusion, and filament runout detection. For temperature protection errors, first confirm the hardware and temperature curve; do not bypass the issue by disabling protection.

Error 'XXX mcu' shutdown: ADC out of range / Not a valid ADC pin​

Error Message: ADC out of range, Not a valid ADC pin, abnormal temperature detection.

Loading...

Cause: Klipper detects that the temperature is outside the configured allowable range, or the pin specified by sensor_pin lacks ADC sampling capability. Commonly caused by an open or shorted thermistor, wiring errors, incorrect thermistor model configuration, pin configuration errors, or a typo in the pin number.

Note

Temporarily relaxing min_temp and max_temp should only be used for troubleshooting, not as a permanent configuration. After identifying the issue, restore them to safe ranges immediately to prevent temperature protection from being disabled.

Troubleshooting Sequence:

Power Off

Before checking the thermistor, heater cartridge, heat bed, fuse, SSR, MOS tube, or power-related wiring, completely turn off the printer, disconnect the power supply, and wait for the hot end and heat bed to cool down. Do not disassemble the power supply, touch exposed power terminals, or inspect mains-voltage heat bed wiring.

  1. After powering off and waiting for cooling, check if the thermistor is firmly plugged in and if the wires are broken or shorted.
  2. Check if the thermistor model and pin configuration match the actual hardware.
  3. If necessary, temporarily relax the temperature range to confirm reading changes, e.g., lower min_temp and raise max_temp.
  4. After finding and resolving the wiring or configuration issue, immediately restore the original safe temperature limits.
  5. Save and restart Klipper.

Related configuration reference: Heating Related.

Heater Not Heating at Expected Rate​

Error Message: The heater is not heating up at the expected rate. Logs may show Heater extruder not heating at expected rate or Heater heater_bed not heating at expected rate.

Loading...

Common Causes:

  • Abnormal output from the heater cartridge, heat bed, SSR, or MOS tube.
  • Poor thermistor contact, partially broken wires, or fluctuating readings.
  • A fan blowing directly on the hot end, heat bed, or heating area, causing slow temperature rise.
  • Insufficient heat bed power or max_power set too low.
  • Inappropriate PID parameters causing large fluctuations near the target temperature.

Solution:

Power Off

Before checking the heater, thermistor, heat bed, fuse, SSR, MOS tube, or power-related wiring, completely turn off the printer, disconnect the power supply, and wait for the hot end and heat bed to cool down. Do not disassemble the power supply, touch exposed power terminals, or inspect mains-voltage heat bed wiring.

  1. After powering off and waiting for cooling, check that the heater and thermistor wiring is secure.
  2. Observe the temperature curve to confirm if the temperature rise is continuous and if there are abnormal fluctuations.
  3. Check if any fan is blowing directly on the hot end or heat bed.
  4. For issues with SSR, MOS tube, power supply wattage, or high-voltage heat beds, average users should prioritize troubleshooting by replacing complete modules, checking the web temperature curve, and contacting after-sales support. Do not disassemble or perform electrical tests yourself.
  5. After confirming the hardware is normal, re-run PID calibration.
  6. If it's confirmed that slow heating is only due to a large heat bed or special structure, refer to verify_heater Optimization.

Related configuration reference: Heating Related, M109 Optimization.

Abnormal Temperature Reading (Displaying 0°C or Constant Fluctuation)​

Error Message: Temperature displays as 0°C, a negative value, or shows constant large fluctuations (±10°C or more).

Common Causes:

  • Broken thermistor wire (displays 0 or very low value).
  • Shorted thermistor (displays extremely high value or triggers ADC out of range).
  • sensor_type configuration does not match the actual thermistor model.
  • PT100 sensor missing pullup_resistor configuration.
  • Thermocouple signal interference, requiring filter_length or thermocouple_max_error configuration.
  • ADC noise interference.

Solution:

  1. Execute QUERY_ADC SENSOR=extruder_temp to view the raw ADC reading.
  2. Execute M105 to view the current temperature reading.
  3. Confirm sensor_type matches the hardware. Common types are NTC 100K beta 3950, PT100, MAX31865, etc.
  4. For PT100 sensors, check sensor_pin, rtd_reference_r, and rtd_num_of_wires.
  5. For thermocouples, check thermocouple_max_error. If ADC noise is high, check filter_length.

Related configuration reference: Heating Related.

MCU shutdown: Verify heater extruder/heater_bed​

Error Message: MCU 'mcu' shutdown: Verify heater extruder or Verify heater heater_bed.

Cause: Klipper's built-in verify_heater safety check detected that the heater temperature change did not meet expectations. This could be due to abnormal heater output, unreliable thermistor readings, SSR response delay, or the heating curve of a high-power heat bed not matching the default detection parameters.

Note

Do not disable the verify_heater function or set its thresholds to extremely unreasonable values just to bypass the error. This removes Klipper's last layer of safety validation for the heater and thermistor.

Common Scenarios:

  • Large heat bed + SSR: Mismatch between SSR switching response, heat bed thermal mass, and default heating_gain.
  • After replacing the heater cartridge, heat bed, or thermistor, the thermal characteristics of the new hardware are incompatible with the old PID and validation parameters.
  • A fan blowing on the hot end causes temperature fluctuations due to ambient airflow exceeding the max_error range.
  • Poor thermistor contact or loose mounting causing intermittent reading jumps.
  • Unstable power supply voltage or insufficient power supply wattage.

Troubleshooting Method:

Power Off

Before checking the heater, thermistor, SSR, MOS tube, fuse, or power-related wiring, completely turn off the printer, disconnect the power supply, and wait for the hot end and heat bed to cool down. Do not disassemble the power supply, touch exposed terminals, or inspect mains-voltage heat bed wiring.

  1. First, power off and check if the thermistor is plugged in securely and the heater wiring is tight.
  2. Observe the temperature curve in klippy.log just before the shutdown. If the curve rises steadily without jumps, the parameters are likely too sensitive. If there are intermittent jumps, drops to zero, or spikes, prioritize fixing the hardware issue.
  3. Check the [verify_heater extruder] or [verify_heater heater_bed] configuration section.
  4. After confirming the hardware is normal, re-run PID calibration, then observe if the false trigger still occurs.
  5. For more detailed parameter explanations and tuning examples, refer to verify_heater Optimization.

HOST temperature above maximum temperature​

Error Message: HOST temperature xx above maximum temperature or MCU temperature not supported on xxx.

Common Causes:

  • The host CPU temperature is too high, exceeding the max_temp in [temperature_host].
  • The mainboard MCU's internal temperature sensor is not supported by the current firmware/chip.
  • Insufficient host cooling, such as a sealed enclosure, stalled fan, or high ambient temperature.

Solution:

  1. Check the host's heatsink, fan, and enclosure ventilation.
  2. Use vcgencmd measure_temp, sensors, or system monitoring tools to check the CPU temperature.
  3. If the threshold is simply set too low, adjust the [temperature_host] max_temp appropriately, but do not disable temperature protection.
  4. If you get MCU temperature not supported, delete or comment out the [temperature_mcu] configuration for the unsupported MCU.

Related configuration reference: Fan Reference Configuration.

Requested temperature out of range​

Error Message: Requested temperature (285.0) out of range (0.0:130.0), Requested temperature (-5.0) out of range (0.0:300.0), Unknown temperature sensor 'xxx', Sensor 'xxx' temperature xxx not in range, Unable to open temperature file 'xxx'.

Common Causes:

  • A macro passes the nozzle temperature to the heat bed, or the heat bed temperature to the nozzle, causing the target temperature to be outside the corresponding heater's range.
  • Slicer variable names are inconsistent with Klipper macro parameter names, resulting in the macro receiving null, default, or incorrectly calculated values.
  • Unreasonable min_temp / max_temp settings in [extruder], [heater_bed], [temperature_sensor].
  • TEMPERATURE_WAIT, SET_HEATER_TEMPERATURE, or fan control commands use a sensor name that does not exist.
  • The system temperature file pointed to by [temperature_host] does not exist or is not supported by the current system.
  • After upgrading Klipper, old configurations or vendor configurations still use outdated temperature sensor names, such as AHT20_F. Solution:
  1. Check the temperature range indicated in the error to determine whether the nozzle, heated bed, motherboard temperature, or host computer temperature has exceeded the limit.
  2. Review the start macro and slicer parameters to ensure parameter names such as BED, BED_TEMP, HOTEND, and EXTRUDER_TEMP correspond correctly.
  3. Set reasonable default values for temperature parameters in the macro and use |float for conversion.
  4. Do not simply raise max_temp significantly to bypass the error; first confirm that parameters and sensor configuration are correct.
  5. If you encounter Unknown temperature sensor, check whether the sensor name in the command matches the configuration section name.
  6. If you encounter Unknown temperature sensor 'AHT20_F', first search for AHT20_F in printer.cfg and all [include] files to determine which [heater_generic], [temperature_sensor], or vendor extension configuration section it belongs to.

Unknown temperature sensor​

Error Message: Unknown temperature sensor 'AHT20_F', Unknown temperature sensor 'xxx'.

Common Causes:

  • A command, macro, or temperature-controlled fan references a non-existent sensor section name.
  • The configuration file introduces an outdated vendor configuration via [include], and the sensor name is no longer compatible after upgrading Klipper.
  • The sensor_type syntax for AHT10 / AHT20 / AHT21 / AHT30 temperature and humidity sensors does not match the current Klipper version.
  • A temperature sensor configuration section has been deleted, but macros, [verify_heater], [temperature_fan], or vendor extensions still reference it.

Solution:

  1. Search for the sensor name reported in the error within printer.cfg and all include files; do not only check the main configuration file.
  2. Determine whether the reported name is the sensor_type or the configuration section name. For example, the command reference name for [temperature_sensor chamber] is typically chamber.
  3. For AHT series sensors, prioritize filling in according to the current Klipper configuration reference; the AHT20_F in older configurations is not a universal syntax. After upgrading, you can try changing it to AHT10 or AHT2X based on actual support for testing.
  4. If the sensor originates from a vendor extension feature, first confirm whether the current system still includes the corresponding extension module; when the module is missing, do not just change the name—simultaneously verify whether the entire vendor configuration set is compatible with the current Klipper.
  5. After modification, execute RESTART, then check klippy.log for any other configuration errors.

Related Configuration References: Heating, Macros.

Thermocouple reader fault​

Error Message: MCU 'mcu' shutdown: Thermocouple reader fault. The log may also contain fields related to max31865 or max31855.

Common Causes:

  • The MAX31865 only supports PT100 / PT1000 platinum resistance probes; connecting an NTC100K thermistor will directly trigger this error.
  • The temperature momentarily exceeds the max_temp setting (even a fluctuation of 1–2°C can trigger it).
  • Poor SPI wiring of the MAX31865 / MAX31855 module, or incorrect configuration of spi_bus or cs_pin.
  • The probe wire is broken, has poor contact, or the terminal is oxidized.
  • The parameters rtd_nominal_r, rtd_reference_r, or rtd_num_of_wires do not match the actual module.

Solution:

Power Off Operation

Before checking the temperature sensor, heater cartridge, or SPI wiring, completely shut down the printer, disconnect the power supply, and wait for the hot end to cool.

  1. Confirm the sensor type: The MAX31865 can only be used with PT100 / PT1000, not NTC thermistors. If you are using an NTC100K probe, it should be connected to the mainboard's standard thermistor interface (TH0/TH1), not through the MAX31865.
  2. Check if max_temp has a sufficient margin. For example, if printing at 250°C, it is recommended to set max_temp to 260–280 to prevent PID fluctuations from instantly triggering protection.
  3. After powering off, check if the SPI wiring (MOSI, MISO, SCK, CS) of the MAX31865 module is secure, and that cs_pin matches the configuration.
  4. Verify rtd_nominal_r (use 100 for PT100, 1000 for PT1000) and rtd_reference_r (typically 430 or 4300, depending on the module's silkscreen or datasheet).
  5. Confirm that rtd_num_of_wires matches the actual number of probe wires (2-wire / 3-wire / 4-wire).
  6. After modification, execute FIRMWARE_RESTART and observe if the temperature reading is normal.

Configuration Example (PT1000 + MAX31865):

[temperature_sensor extruder]
sensor_type: MAX31865
sensor_pin: toolboard:PA4
spi_bus: spi1
rtd_nominal_r: 1000
rtd_reference_r: 4300
rtd_num_of_wires: 2

Note: Pins like sensor_pin and spi_bus should be based on the actual silkscreen of your mainboard or toolboard; do not copy the example verbatim.

Related Configuration References: Heating.

Long wait after reaching temperature, print does not start​

Symptom: After starting the print, the nozzle or heated bed reaches the target temperature, but the print hesitates for a long time. The temperature fluctuates above and below the target value, the wait time is excessively long (sometimes several minutes or even 10 minutes), and there is no !! error in klippy.log.

Common Causes:

  • Klipper's M109 / M190 does not continue after reaching the target temperature once; instead, it waits for the temperature to settle near the target value. The official G-Codes documentation states that M109 always waits for temperature to settle at requested value.
  • The temperature oscillates around the target value and cannot stabilize quickly: Inappropriate PID parameters, excessive heating power, or a thermistor too close to the heater block (low thermal mass, fast response) can all prolong the settling time.
  • The slicer's start G-code uses serial waiting, first M190 for the bed, then M109 for the nozzle, which adds up the total wait time.

Solution:

  1. First, perform PID calibration (PID_CALIBRATE) to achieve smoother temperature control, which is fundamental for reducing oscillations.
  2. Use tolerance window waiting instead of waiting for complete stability: proceed once the temperature enters a reasonable range near the target, instead of waiting for it to be perfectly stable. See the Optimize M109 / M190 Temperature Wait macro for details. This macro first sets the temperature with M104/M140, then uses TEMPERATURE_WAIT SENSOR=extruder MINIMUM={s-5} MAXIMUM={s+5} to proceed once inside the tolerance window.
  3. If oscillations are obvious, try reducing the heater's max_power (e.g., 0.9–0.95) or increasing pwm_cycle_time (e.g., 0.05), then re-run PID calibration.
  4. Heat the nozzle and bed in parallel: In the start macro, use M140/M104 to set both temperatures simultaneously, then wait with M190/M109 separately to avoid serial wait time accumulation.
  5. For high-temperature beds (70°C and above), warping takes time. After reaching temperature, you can add a G4 P30000 wait (approximately 30 seconds) before homing or leveling.
How to Identify This Issue

Observe the temperature graph: if the temperature has already reached the target value but continues to fluctuate up and down for a long time without settling into a stable range, and there is no !! error in klippy.log, it is typically a "waiting for temperature settle" induced long wait, not a hardware fault.

Related Documents: Optimize M109 / M190 Temperature Wait, Heating, Macros

Extrusion Issues​

Extrude below minimum temp​

Error Message: The nozzle temperature is below the minimum temperature allowed for extrusion. The log may show Extrude below minimum temp or Extruder not hot enough.

Common Causes:

  • The slicer's start G-code calls PRINT_START without passing temperature parameters (e.g., EXTRUDER_TEMP, BED_TEMP), and the default(0) in the macro causes M109 S0 to turn off the heater, triggering the error upon subsequent extrusion attempts.
  • The start macro performs extrusion (e.g., wiping, priming line) while the nozzle is still at a soaking temperature (e.g., 150°C), which is below min_extrude_temp (default 170°C).
  • The PAUSE / RESUME / M600 macros lack commands to wait for temperature recovery before extruding after resuming.
  • During printing, the temperature inadvertently drops below min_extrude_temp (poor thermistor contact, fan directed at the hot end, PID issues).

Solution:

  1. Check the slicer's start G-code to ensure that PRINT_START is called with correct temperature parameters, for example: PRINT_START EXTRUDER_TEMP={first_layer_temperature[initial_extruder]} BED_TEMP={first_layer_bed_temperature[initial_extruder]}.
  2. Review the default values for temperature variables in the PRINT_START macro definition. Avoid default(0) which leads to M109 S0 turning off the heater. It is recommended to set a reasonable low default value (e.g., default(190)) or skip the wait command if the parameter is 0.
  3. Ensure that extrusion actions (wiping, priming line) in the start macro are performed after M109 waiting for the print temperature, not during the soaking temperature phase.
  4. Check if macros like M600, PAUSE, RESUME include temperature wait commands. Before resuming printing, use M109 to wait for the nozzle to return to operating temperature.
  5. Examine the thermistor and temperature curve to ensure the reading is stable.
  6. It is not recommended to lower min_extrude_temp permanently just to bypass the error.
How to Determine if It’s a Parameter Passing Issue

Search for Stats lines before the error in klippy.log: if extruder: target=0 or the target is far below the printing temperature (e.g., 150), while the slicer’s set printing temperature is above 200°C, it’s usually a sign that the start macro parameters were not passed correctly.

Related configuration references: M109 Optimization, Macro Introduction.

Extrude only move too long​

Error Message: Extrude only move too long (xxmm vs xxmm).

Solution:

  1. Check the slicer’s retraction length; do not blindly set it too high even for Bowden remote extruders.
  2. Check whether the loading, unloading, or nozzle wiping macro uses an excessively long extrusion or retraction distance in one move.
  3. Check whether the E-axis state is correct when resuming printing, to avoid using historical E values as new relative extrusion distances.
  4. Check whether M82 / M83 and G92 E0 are correctly used in the macros.
  5. If long pure extrusion is truly necessary, appropriately increase max_extrude_only_distance in [extruder], but do not use an extremely large value to mask macro state errors.

Related configuration references: Extruder Reference Configuration, Macro Introduction.

Move exceeds maximum extrusion​

Error Message: Move exceeds maximum extrusion (xxmm^2 vs xxmm^2).

Solution:

  1. Check whether the slicer’s filament diameter, nozzle diameter, extrusion multiplier, and line width are abnormal.
  2. Check whether the start line, wipe line, filament change, purge tower, or purge macro generates an abnormally large E value.
  3. Check whether the M82 / M83 extrusion mode and G92 E0 in the start/pause/resume macros match the slicer.
  4. Check nozzle_diameter, filament_diameter, or max_extrude_cross_section in [extruder].
  5. After changing the nozzle diameter, synchronously update the Klipper configuration and the slicer’s nozzle, line width, and extrusion multiplier.
  6. It’s not recommended to directly increase max_extrude_cross_section significantly; first confirm that G-code and slicer parameters are normal.

Related configuration references: Extruder Reference Configuration, Machine Calibration.

Extrude when no extruder present / Extruder not configured​

Error Message: Extrude when no extruder present, Extruder not configured, or Active extruder does not have a stepper.

Solution:

  1. Confirm that the main extruder configuration section is named [extruder].
  2. For multi-extruder or synchronized extrusion scenarios, check [extruder_stepper] and SYNC_EXTRUDER_MOTION.
  3. Check whether ACTIVATE_EXTRUDER, T0/T1, or custom switching commands in macros point to actual configuration sections.

Related configuration references: Extruder Reference Configuration.

Filament Detection and M600 Filament Change Errors​

Error Messages: Filament sensor: runout detected, the M600 macro interrupts printing and cannot resume, the filament detection switch is always triggered or never triggered, or Timer too close is triggered after waiting for a period during a filament change.

Solution:

Power Off Operation

Before checking, unplugging, or replacing the filament detection sensor wiring, completely turn off the printer and disconnect the power supply. Do not plug or unplug the sensor module or sort interface wiring while the printer is powered on.

  1. Execute QUERY_FILAMENT_SENSOR SENSOR=<sensor name> to confirm that the status is open (or not triggered) when filament is inserted, and changes when filament is removed.
  2. If the status never changes, power off the printer and check the sensor wiring, switch_pin, and pull-up configuration.
  3. If false triggering occurs frequently during printing, check whether the wiring is excessively bent in the cable chain or pulled by moving axes.
  4. Check the M600 macro logic to confirm that the pause, retraction, lift, and resume processes are normal.
  5. In multi-extruder setups, confirm that ACTIVATE_EXTRUDER and the filament detection logic operate on the same extruder.
  6. If Timer too close is triggered only after waiting for a while and then clicking resume, check whether the filament change macro repeatedly calls PAUSE, re-enables filament detection during the pause, or immediately executes a large number of extrusion/movement commands after resuming.
  7. Check whether SAVE_GCODE_STATE / RESTORE_GCODE_STATE names match, and if necessary, reduce beeps, light effects, delay macros, and remote plugin actions before and after resume.

Timer too close after M600 Filament Change​

Error Message: After executing M600, a filament change triggered by runout, or a manual filament change, waiting tens of seconds and then clicking resume results in MCU 'mcu' shutdown: Timer too close.

Common Causes:

  • The filament change macro, filament detection, and front-end pause/resume logic are nested, causing a second pause when printing is already paused.
  • Immediately executing long-distance extrusion, nozzle wiping, beeping, lighting effects, or UPDATE_DELAYED_GCODE upon resume increases scheduling pressure on lower-performance host machines.
  • The filament detection sensor is not temporarily disabled during filament change, and the loading process triggers runout again.
  • After updating Klipper, old macro assumptions about pause/resume states and motion queues are no longer valid for the current version.

Solution:

  1. First, examine the full klippy.log to check for Print already paused, Unknown g-code state, Filament sensor, or macro template errors before Timer too close.
  2. Search for SAVE_GCODE_STATE, RESTORE_GCODE_STATE, and UPDATE_DELAYED_GCODE in the M600, PAUSE, RESUME, LOAD_FILAMENT, and UNLOAD_FILAMENT macros.
  3. Temporarily disable filament detection during the filament change, and re-enable it after the system stabilizes.
  4. Reduce the extrusion length, speed, and number of consecutive actions during the resume phase to avoid accumulating a large number of motion commands at once.
  5. If the issue only occurs on lower-performance host machines, temporarily disable the camera, KlipperScreen, and remote control plugins and retest.

System-Level Troubleshooting: Timer too close

Related configuration references: Macro Introduction, Filament Detection Reference Configuration.

Loading...