跳到主要内容

温度、加热与挤出报错

本页整理温度传感器、加热器、热床、挤出和断料检测相关报错。温度保护类报错应先确认硬件和温度曲线，不要通过关闭保护来绕过问题。

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

报错信息：ADC out of range、Not a valid ADC pin，温度检测异常。

Loading...

报错原因：Klipper 检测到温度超过配置允许范围，或 sensor_pin 指定的引脚不具备 ADC 采样能力。常见于热敏电阻开路、短路、接线错误、热敏型号配置错误、引脚配置错误或引脚编号写错。

注意

临时放宽 min_temp 和 max_temp 只能用于排查，不能作为长期配置。确认问题后必须恢复到安全范围，避免温度保护失效。

排查顺序：

断电操作

检查热敏电阻、加热棒、热床、保险丝、SSR、MOS 管或电源相关线束前，请完全关闭打印机并断开电源供应，并等待热端和热床冷却。不要拆卸电源、触碰裸露电源端子或检查市电热床高压接线。

  1. 断电并等待冷却后，检查热敏电阻是否插牢，线材是否断裂或短路。
  2. 检查热敏型号和引脚配置是否与实际硬件一致。
  3. 必要时临时放宽温度范围用于确认读数变化，例如将 min_temp 改低、max_temp 改高。
  4. 找到并解决接线或配置问题后，立即恢复原来的安全温度限制。
  5. 保存并重启 Klipper。

相关配置参考：加热相关。

加热器升温速率异常（Heater not heating at expected rate）​

报错信息：加热器没有按预期速度升温，日志中可能出现 Heater extruder not heating at expected rate 或 Heater heater_bed not heating at expected rate。

Loading...

常见原因：

  • 加热棒、热床或 SSR / MOS 管输出异常。
  • 热敏电阻接触不良、线材半断或读数跳变。
  • 风扇直吹热端、热床或加热区域，导致升温过慢。
  • 热床功率不足，或 max_power 限制过低。
  • PID 参数不合适，温度接近目标时波动过大。

解决方法：

断电操作

检查加热器、热敏电阻、热床、保险丝、SSR、MOS 管或电源相关线束前，请完全关闭打印机并断开电源供应，并等待热端和热床冷却。不要拆卸电源、触碰裸露电源端子或检查市电热床高压接线。

  1. 断电并等待冷却后，检查加热器和热敏电阻接线是否牢固。
  2. 观察温度曲线，确认升温是否连续、是否有异常跳变。
  3. 检查是否有风扇直吹热端或热床。
  4. 对于 SSR、MOS 管、电源功率或高压热床问题，普通用户应优先通过替换成品模块、检查网页温度曲线和联系售后来排查，不要自行拆解或进行电气检测。
  5. 确认硬件正常后重新执行 PID 校准。
  6. 如果确认只是大尺寸热床或特殊结构导致升温慢，可参考 verify_heater 优化。

相关配置参考：加热相关、M109 优化。

温度读数异常（温度显示 0°C 或持续跳变）​

报错信息：温度显示为 0°C、负数或读数持续大幅跳变（±10°C 以上）。

常见原因：

  • 热敏电阻断线（显示 0 或极低值）。
  • 热敏电阻短路（显示极高值或触发 ADC out of range）。
  • sensor_type 配置与实际热敏型号不匹配。
  • PT100 传感器缺少 pullup_resistor 配置。
  • 热电偶信号干扰，需要 filter_length 或 thermocouple_max_error 配置。
  • ADC 噪声干扰。

解决方法：

  1. 执行 QUERY_ADC SENSOR=extruder_temp 查看原始 ADC 读数。
  2. 执行 M105 查看当前温度读数。
  3. 确认 sensor_type 与硬件一致，常见为 NTC 100K beta 3950、PT100、MAX31865 等。
  4. PT100 传感器需检查 sensor_pin、rtd_reference_r、rtd_num_of_wires。
  5. 热电偶可检查 thermocouple_max_error，ADC 噪声大时可检查 filter_length。

相关配置参考：加热相关。

MCU shutdown: Verify heater extruder/heater_bed​

报错信息：MCU 'mcu' shutdown: Verify heater extruder 或 Verify heater heater_bed。

报错原因：Klipper 内置 verify_heater 安全检查检测到加热器温度变化不符合预期，可能是加热器输出异常、热敏读数不可信、SSR 响应延迟或大功率热床升温曲线与默认检测参数不匹配。

注意

不要为了绕过报错而直接关闭 verify_heater 功能或将其阈值设置为极不合理的值。这会移除 Klipper 对加热器和热敏的最后一层安全校验。

常见场景：

  • 大尺寸热床 + SSR：SSR 开关响应、热床热容和默认 heating_gain 不匹配。
  • 更换加热棒、热床或热敏后，新硬件的热特性与旧 PID 和校验参数不兼容。
  • 风扇直吹热端，环境气流导致温度波动超出 max_error 范围。
  • 热敏接触不良或安装松动，读数断续跳变。
  • 供电电压不稳或电源功率不足。

排查方法：

断电操作

检查加热器、热敏、SSR、MOS 管、保险丝或电源相关线束前，请完全关闭打印机并断开电源供应，并等待热端和热床冷却。不要拆卸电源、触碰裸露端子或检查市电热床高压接线。

  1. 先断电检查热敏是否插牢、加热器接线是否牢固。
  2. 观察 klippy.log 中 shutdown 前的温度曲线。如果曲线稳定上升且不跳变，更可能是参数太敏感；如果断续跳变、归零或飙升，则优先处理硬件问题。
  3. 检查 [verify_heater extruder] 或 [verify_heater heater_bed] 配置段。
  4. 确认硬件正常后重新执行 PID 校准，再观察是否仍误触发。
  5. 更详细的参数说明和调优示例参考 verify_heater 优化。

HOST temperature above maximum temperature​

报错信息：HOST temperature xx above maximum temperature 或 MCU temperature not supported on xxx。

常见原因：

  • 上位机 CPU 温度过高，超过 [temperature_host] 中的 max_temp。
  • 主板 MCU 内置温度传感器不受当前固件/芯片支持。
  • 上位机散热不足，外壳密闭、风扇停转或环境温度过高。

解决方法：

  1. 检查上位机散热片、风扇和外壳通风。
  2. 使用 vcgencmd measure_temp、sensors 或系统监控查看 CPU 温度。
  3. 若只是阈值设置过低，适当调整 [temperature_host] max_temp，但不要关闭温度保护。
  4. 如果报 MCU temperature not supported，删除或注释不受支持 MCU 的 [temperature_mcu] 配置。

相关配置参考：风扇参考配置。

Requested temperature out of range​

报错信息：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'。

常见原因：

  • 宏把喷嘴温度传给热床，或把热床温度传给喷嘴，导致目标温度超过对应加热器范围。
  • 切片器变量名和 Klipper 宏参数名不一致，宏拿到空值、默认值或错误计算结果。
  • [extruder]、[heater_bed]、[temperature_sensor] 的 min_temp / max_temp 设置不合理。
  • TEMPERATURE_WAIT、SET_HEATER_TEMPERATURE 或温控风扇命令中填写了不存在的传感器名称。
  • [temperature_host] 指向的系统温度文件不存在或当前系统不支持。
  • 升级 Klipper 后，旧配置或厂商配置中仍使用不再匹配的温湿度传感器名称，例如 AHT20_F。

解决方法：

  1. 查看报错中的温度范围，先判断是喷嘴、热床、主板温度还是上位机温度超限。
  2. 检查起始宏和切片器传参，确认 BED、BED_TEMP、HOTEND、EXTRUDER_TEMP 等参数名称对应正确。
  3. 在宏中给温度参数设置合理默认值，并使用 |float 转换。
  4. 不要为了绕过报错直接大幅提高 max_temp；先确认传参和传感器配置正确。
  5. 如果报 Unknown temperature sensor，检查命令里的传感器名称是否与配置段名称一致。
  6. 如果报 Unknown temperature sensor 'AHT20_F'，先在 printer.cfg 和所有 [include] 文件中搜索 AHT20_F，确认它属于哪个 [heater_generic]、[temperature_sensor] 或厂商扩展配置段。

Unknown temperature sensor​

报错信息：Unknown temperature sensor 'AHT20_F'、Unknown temperature sensor 'xxx'。

常见原因：

  • 命令、宏或温控风扇引用了不存在的传感器段名。
  • 配置文件通过 [include] 引入了旧版厂商配置，升级 Klipper 后传感器名称不再兼容。
  • AHT10 / AHT20 / AHT21 / AHT30 温湿度传感器的 sensor_type 写法与当前 Klipper 版本不匹配。
  • 删除了某个温度传感器配置段，但宏、[verify_heater]、[temperature_fan] 或厂商扩展仍在引用它。

解决方法：

  1. 在 printer.cfg 和所有 include 文件中搜索报错里的传感器名称，不要只看主配置文件。
  2. 确认报错名称是 sensor_type，还是配置段名。例如 [temperature_sensor chamber] 的命令引用名通常是 chamber。
  3. AHT 系列传感器优先按当前 Klipper 配置参考填写；旧配置中的 AHT20_F 不是通用写法，升级后可按实际支持情况改为 AHT10 或 AHT2X 测试。
  4. 如果该传感器来自厂商扩展功能，先确认当前系统是否仍包含对应扩展模块；缺少模块时不要只改名称，应同步确认整套厂商配置是否兼容当前 Klipper。
  5. 修改后执行 RESTART，再查看 klippy.log 中是否还有其他配置错误。

相关配置参考：加热相关、宏介绍。

Thermocouple reader fault​

报错信息：MCU 'mcu' shutdown: Thermocouple reader fault，日志中可能伴随 max31865 或 max31855 相关字段。

常见原因：

  • MAX31865 仅支持 PT100 / PT1000 铂电阻探头，接了 NTC100K 热敏电阻会直接报此错误。
  • 温度瞬间超过 max_temp 设定值（即使只超出 1–2°C 的波动也会触发）。
  • MAX31865 / MAX31855 模块的 SPI 接线不良、spi_bus 或 cs_pin 配置错误。
  • 探头线材断裂、接触不良或接线端子氧化。
  • rtd_nominal_r、rtd_reference_r、rtd_num_of_wires 参数与实际模块不匹配。

解决方法：

断电操作

检查温度传感器、加热棒或 SPI 接线前，请完全关闭打印机并断开电源供应，并等待热端冷却。

  1. 确认传感器类型：MAX31865 只能搭配 PT100 / PT1000，不能使用 NTC 热敏电阻。如果你使用的是 NTC100K 探头，应接到主板的普通热敏电阻接口（TH0/TH1），不要走 MAX31865。
  2. 检查 max_temp 是否留有余量。例如实际打印 250°C，建议将 max_temp 设为 260–280，避免 PID 波动瞬间触发保护。
  3. 断电后检查 MAX31865 模块的 SPI 接线（MOSI、MISO、SCK、CS）是否牢固，cs_pin 是否与配置一致。
  4. 核对 rtd_nominal_r（PT100 填 100，PT1000 填 1000）和 rtd_reference_r（通常为 430 或 4300，以模块丝印或说明书为准）。
  5. 确认 rtd_num_of_wires 与实际探头线数一致（2 线 / 3 线 / 4 线）。
  6. 修改后执行 FIRMWARE_RESTART，观察温度读数是否正常。

配置示例（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

注意：sensor_pin、spi_bus 等引脚请以你的主板或工具板实际丝印为准，不要照抄示例。

相关配置参考：加热相关。

到温后仍长时间等待，不开始打印​

现象：开始打印后喷嘴或热床升温到目标温度附近，但打印迟迟不开始，温度在目标值上下反复波动，等待时间明显过长（有时长达数分钟甚至 10 分钟），且 klippy.log 中没有 !! 报错。

常见原因：

  • Klipper 的 M109 / M190 不是“到达目标温度一次”就继续，而是等待温度稳定（settle）在目标值附近。官方 G-Codes 文档明确说明 M109 always waits for temperature to settle at requested value。
  • 温度在目标值附近震荡无法快速稳定：PID 参数不合适、加热功率过强，或热敏电阻紧贴加热体（热质量小、响应过快），都会拉长稳定时间。
  • 切片器起始 G-code 中先 M190 等热床、再 M109 等喷嘴，串行等待会叠加总等待时间。

解决方法：

  1. 先执行 PID 校准（PID_CALIBRATE），获得更平稳的控温，这是减少温度震荡的基础。
  2. 用容差窗口等待替代“等待完全稳定”：进入目标温度附近一个合理区间即继续，而不是等温度彻底平稳。具体宏见 优化 M109 / M190 温度等待，该宏会先用 M104/M140 设温，再用 TEMPERATURE_WAIT SENSOR=extruder MINIMUM={s-5} MAXIMUM={s+5} 进入容差即继续。
  3. 若震荡明显，可适当降低加热器 max_power（如 0.9–0.95）或增大 pwm_cycle_time（如 0.05），修改后重新做 PID 校准。
  4. 让喷嘴与热床并行加热：起始宏先用 M140/M104 同时设温，再分别 M190/M109 等待，避免串行等待叠加。
  5. 高温热床（70°C 以上）形变需要时间，可在到温后用 G4 P30000 额外等待约 30 秒再归位或调平。
如何判断属于本问题

在温度曲线中观察：如果温度已经到达目标值，但仍在目标值上下持续波动、长时间无法停在稳定区间，且 klippy.log 中没有 !! 报错，通常就是“等待温度稳定”导致的长时间等待，而非硬件故障。

相关文档：优化 M109 / M190 温度等待、加热相关、宏介绍

挤出问题​

Extrude below minimum temp​

报错信息：喷嘴温度低于允许挤出的最低温度，日志中可能出现 Extrude below minimum temp 或 Extruder not hot enough。

常见原因：

  • 切片器起始 G-code 调用 PRINT_START 时未传递温度参数（如 EXTRUDER_TEMP、BED_TEMP），宏内 default(0) 导致 M109 S0 关闭加热器，随后挤出动作触发报错。
  • 起始宏中先执行了挤出（如擦嘴、画线）但此时喷嘴仍处于浸泡温度（如 150°C），低于 min_extrude_temp（默认 170°C）。
  • PAUSE / RESUME / M600 宏中缺少等待温度恢复的命令，恢复后直接挤出。
  • 打印过程中温度意外掉到 min_extrude_temp 以下（热敏接触不良、风扇直吹、PID 异常）。

解决方法：

  1. 检查切片器起始 G-code，确认调用 PRINT_START 时传递了正确的温度参数，例如：PRINT_START EXTRUDER_TEMP={first_layer_temperature[initial_extruder]} BED_TEMP={first_layer_bed_temperature[initial_extruder]}。
  2. 检查 PRINT_START 宏定义中温度变量的默认值，避免 default(0) 导致 M109 S0 关闭加热器；建议默认值设为合理低温（如 default(190)）或在参数为 0 时跳过等待。
  3. 确认起始宏中挤出动作（擦嘴、画线）在 M109 等待打印温度之后执行，而非在浸泡温度阶段。
  4. 检查 M600、PAUSE、RESUME 等宏中是否有等待温度命令，恢复打印前应先 M109 等待喷嘴回到工作温度。
  5. 检查热敏电阻和温度曲线，确认温度读数稳定。
  6. 不建议为了绕过报错长期降低 min_extrude_temp。
如何判断属于参数传递问题

在 klippy.log 中搜索报错前的 Stats 行：如果 extruder: target=0 或 target 远低于打印温度（如 150），而切片器设定的打印温度为 200°C 以上，通常就是起始宏参数未正确传递。

相关配置参考：M109 优化、宏介绍。

Extrude only move too long​

报错信息：Extrude only move too long (xxmm vs xxmm)。

解决方法：

  1. 检查切片机回抽长度，Bowden 远程挤出也不要盲目设置过大。
  2. 检查换料、装料、退料或擦嘴宏中是否一次挤出/回抽距离过长。
  3. 检查恢复打印时 E 坐标状态是否正确，避免把历史 E 值当作新的相对挤出距离。
  4. 检查宏中是否正确使用 M82 / M83 和 G92 E0。
  5. 如确实需要长距离纯挤出，可在 [extruder] 中适当增大 max_extrude_only_distance，但不要用极大值掩盖宏状态错误。

相关配置参考：挤出机参考配置、宏介绍。

Move exceeds maximum extrusion​

报错信息：Move exceeds maximum extrusion (xxmm^2 vs xxmm^2)。

解决方法：

  1. 检查切片机耗材直径、喷嘴直径、挤出倍率和线宽是否异常。
  2. 检查起始线、擦嘴线、换料、擦料塔或 purge 宏是否生成了异常大的 E 值。
  3. 检查起始/暂停/恢复宏中的 M82 / M83 挤出模式和 G92 E0 是否与切片器一致。
  4. 检查 [extruder] 中 nozzle_diameter、filament_diameter 或 max_extrude_cross_section。
  5. 更换喷嘴直径后，同步修改 Klipper 配置和切片器喷嘴、线宽、挤出倍率。
  6. 不建议直接大幅提高 max_extrude_cross_section；应先确认 G-code 和切片参数正常。

相关配置参考：挤出机参考配置、机器校准。

Extrude when no extruder present / Extruder not configured​

报错信息：Extrude when no extruder present、Extruder not configured 或 Active extruder does not have a stepper。

解决方法：

  1. 确认主挤出机配置段名称为 [extruder]。
  2. 多挤出或同步挤出场景，检查 [extruder_stepper] 和 SYNC_EXTRUDER_MOTION。
  3. 检查宏中的 ACTIVATE_EXTRUDER、T0/T1 或自定义切换命令是否指向真实配置段。

相关配置参考：挤出机参考配置。

断料检测与 M600 换料报错​

报错信息：Filament sensor: runout detected、M600 换料宏执行后打印中断无法恢复、断料检测开关始终处于触发或未触发状态、换料等待一段时间后恢复触发 Timer too close。

解决方法：

断电操作

检查、拔插或更换断料检测传感器线束前，请完全关闭打印机并断开电源供应。不要在通电状态下插拔传感器模块或整理接口线序。

  1. 执行 QUERY_FILAMENT_SENSOR SENSOR=<传感器名>，确认插入耗材时状态为 open（或 not triggered），拔出后状态变化。
  2. 如果状态始终不变，断电后检查传感器接线、switch_pin 和上拉配置。
  3. 如果打印过程中频繁误触发，检查线束是否在拖链中过度弯曲或被运动轴拉扯。
  4. 检查 M600 宏逻辑，确认暂停、回抽、抬升和恢复流程正常。
  5. 多挤出机场景下，确认 ACTIVATE_EXTRUDER 和断料检测逻辑作用的是同一个挤出机。
  6. 如果等待换料一段时间后点击继续才触发 Timer too close，检查换料宏是否在暂停期间重复调用 PAUSE、重复启用断料检测，或在恢复后立即执行大量挤出/移动命令。
  7. 检查 SAVE_GCODE_STATE / RESTORE_GCODE_STATE 名称是否一致，必要时在恢复前后减少提示音、灯效、延迟宏和远程插件动作。

M600 换料后 Timer too close​

报错信息：执行 M600、断料暂停或手动换料后，等待几十秒再点击继续，随后出现 MCU 'mcu' shutdown: Timer too close。

常见原因：

  • 换料宏、断料检测和前端暂停恢复逻辑互相嵌套，导致打印已经暂停时再次暂停。
  • 恢复时立即执行长距离挤出、擦嘴、蜂鸣器、灯效或 UPDATE_DELAYED_GCODE，低性能上位机调度压力升高。
  • 断料检测传感器在换料期间未临时禁用，装料过程再次触发 runout。
  • 更新 Klipper 后，旧宏对暂停/恢复状态和运动队列的假设不再适合当前版本。

解决方法：

  1. 先查看完整 klippy.log，确认 Timer too close 前是否有 Print already paused、Unknown g-code state、Filament sensor 或宏模板报错。
  2. 在 M600、PAUSE、RESUME、LOAD_FILAMENT、UNLOAD_FILAMENT 宏中搜索 SAVE_GCODE_STATE、RESTORE_GCODE_STATE 和 UPDATE_DELAYED_GCODE。
  3. 换料期间临时禁用断料检测，恢复稳定后再重新启用。
  4. 降低恢复阶段的挤出长度、速度和连续动作数量，避免恢复瞬间堆积大量运动命令。
  5. 如果只在低性能上位机上出现，临时关闭摄像头、KlipperScreen 和远程控制插件后复测。

系统类排查：Timer too close

相关配置参考：宏介绍、断料检测参考配置。

Loading...