跳到主要内容

常见报错总览

本页用于快速定位 Klipper 常见报错。请先在 klippy.log 中找到完整报错关键词，再进入对应分类页面处理。

快速索引​

报错类型常见关键字排查入口
连接问题Unable to connect、Invalid CAN uuid、Lost communication、MCU Protocol error、/dev/serial/by-id本页连接问题、MCU ID 配置、CAN 网络与 ID 搜索
配置问题not valid、not a valid config section、must be specified、Unable to parse、SAVE_CONFIG、Option conflict配置类报错
宏与切片器命令Unknown command、Error evaluating 'gcode_macro、jinja2.exceptions.UndefinedError、dict object has no attribute配置类报错
运动归位Move out of range、Must home axis first、No trigger、Endstop still triggered运动、限位与调平报错
G-code 解析Unable to parse move、Invalid speed、Machine does not support G20、G2/G3运动、限位与调平报错、圆弧拟合建议
探针调平Probe triggered、No trigger on probe、samples_tolerance、bed_mesh、BLTouch failed、Z_TILT、QUAD_GANTRY_LEVEL运动、限位与调平报错
温度加热ADC out of range、not heating at expected rate、Verify heater、temperature温度、加热与挤出报错
挤出问题Extrude below minimum temp、Extrude only move too long、Move exceeds maximum extrusion、Filament sensor、M600温度、加热与挤出报错
性能超时Timer too close、Missed scheduling、Stepper too far in past、Rescheduled timer、restarting too fast、SD busy系统、性能与服务报错
TMC 驱动Unable to read tmc uart、Unable to write tmc spi、GSTAT、coil short circuitTMC 报错排查
CAN 网络bytes_invalid、Network is down、No buffer space available、Invalid CAN uuidCAN 网络与 ID 搜索
传感器外设Invalid adxl345 id、No data、Insufficient axis、Eddy current sensor error、Invalid read data加速度计测试与校准、EDDY 问题合集

相关配置页速查​

报错方向推荐参考
配置语法、缩进、注释、重复引脚配置修改说明
归位方向、轴方向、强制移动归位与方向校准指南
限位、TAP、光电限位、接近开关限位相关
无限位归位、虚拟限位灵敏度无限位使用
加热、PID、升温慢、温度保护加热相关、verify_heater 优化、M109 优化
风扇配置、驱动风扇、7040 风扇风扇参考配置
挤出机参数、旋转距离、挤出配置挤出机参考配置、机器校准
起始/结束宏、暂停恢复、调平与网床宏宏介绍
常用调试命令、探针、共振补偿常用调试指令

连接问题​

MCU ID 配置说明​

Klipper 中的 MCU ID 指的是 [mcu] 或 [mcu xxx] 配置段里用于连接控制板的识别信息。不同通信方式写法不同：

连接方式配置项示例
USB 固件serial:serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx
CAN 固件canbus_uuid:canbus_uuid: xxxxxxxxxxxx
上位机 MCUserial:serial: /tmp/klipper_host_mcu

填写规则：

  1. 主板默认使用 [mcu]，工具板或扩展板使用 [mcu tool]、[mcu toolboard] 等自定义名称。
  2. USB 固件只填写 serial:，CAN 固件只填写 canbus_uuid:，不要在同一个 [mcu] 中同时保留两项。
  3. 多 MCU 机器中，每个 [mcu xxx] 都必须使用自己的真实 ID，不要复制同一个 USB ID 或 CAN UUID。
  4. [mcu xxx] 的名称会影响引脚前缀，例如 [mcu tool] 的引脚应写成 tool:gpio13；名称大小写要保持一致。
  5. 文档示例里的 xxxxxxxx 不能直接使用，必须替换为实际搜索到的 ID。

常见错误：

  • 把烧录模式 ID（如包含 katapult、canboot 的 ID）当作 Klipper 固件 ID 使用。
  • USB 固件配置了 canbus_uuid:，或 CAN 固件仍保留旧的 serial:。
  • 工具板配置成 [mcu]，覆盖了主板 MCU 配置。
  • 引脚前缀和 MCU 名称不一致，例如配置是 [mcu toolboard]，引脚却写 tool:gpio13。

USB ID 查询：USB 固件可执行 ls /dev/serial/by-id/* 获取 ID。

CAN ID 查询：CAN 网络与 ID 搜索

工具板配置：工具板 MCU 添加与跨板配置

mcu 'xxx': Unable to connect​

报错信息：上位机无法找到或连接到主板。

Loading...

常见原因：

  • USB 设备 ID 未填写或填写错误。
  • CAN UUID 未填写、填写错误或设备未在线。
  • UTOC、USB 线、CAN 桥接固件或供电异常。
  • CAN0 未启动，或 CAN 网络配置异常。

处理方法：

  1. 打开 klippy.log 并翻到最下方，确认具体错误信息。

  2. 如果出现 [Errno 2]，通常表示没有将搜索到的 USB 设备 ID 添加到 printer.cfg。

    Loading...

  3. 如果出现 Serial connection closed，通常需要重新搜索 CAN ID 并检查 CAN 网络。

    Loading...

  4. 如果出现 Unable to open CAN port: [Errno 19] No such device，通常表示缺少 UTOC 设备、USB 桥接 CAN 固件或 CAN0 设备。

    Loading...

  5. 如果出现 [Errno 100] Network is down 或 [Errno 105] No buffer space available，请按 CAN 网络与 ID 搜索 重新检查 CAN0 配置。

mcu 'mcu': Invalid CAN uuid​

报错信息：CAN UUID 无效或无法识别。

Loading...

报错原因：canbus_uuid: 填写错误、设备不在线，或 CAN 网络未正常通信。

解决方法：

  1. 按 CAN 网络与 ID 搜索 重新搜索 CAN UUID。
  2. 确认 printer.cfg 中填写的是实际搜索到的 UUID。
  3. 确认同一个 [mcu] 中没有同时启用 serial: 和 canbus_uuid:。
  4. 检查 CAN-H、CAN-L、终端电阻、供电和固件 CAN 速率。

Option 'serial' in section 'mcu' must be specified​

报错信息：在 [mcu] 配置段中必须指定 serial。

Loading...

报错原因：USB 固件连接时没有填写 serial:，或者 [mcu] 配置段被误删。

解决方法：

  1. 重新搜索 USB 设备 ID。
  2. 在 printer.cfg 的 [mcu] 配置段中填写：
[mcu]
serial: /dev/serial/by-id/实际搜索到的ID
  1. 保存并重启 Klipper。

如果当前主板刷写的是 CAN 固件，请使用 canbus_uuid:，不要继续填写 serial:。

USB ID 找不到 / 系统服务干扰​

报错信息：执行 ls /dev/serial/by-id/* 没有输出或提示 No such file or directory；Klipper 连接时报 mcu 'xxx': Unable to open serial port、[Errno 2] No such file or directory，或 USB 主板在系统中反复断开重连。

常见原因：

  • 主板未进入 Klipper 固件运行状态，仍处于 Katapult / CanBoot / DFU 等烧录模式。
  • USB 线、USB 口、上位机供电或主板供电异常。
  • Debian 11 Bullseye 部分 udev 版本存在问题，可能不会生成 /dev/serial/by-id/ 设备路径。
  • 桌面版 Linux 可能安装 ModemManager 或 BRLtty，这些服务可能抢占串口设备，导致 Klipper 无法稳定连接主板。

排查方法：

断电操作

重新插拔 USB 线、检查主板供电线或整理 USB / CAN 线束前，请完全关闭打印机并断开电源供应。不要在通电状态下整理接口线序或触碰端子。

  1. 先确认主板已经刷写并运行 Klipper 固件，USB ID 应包含 usb-Klipper，不要把 katapult、canboot、Bootloader 或 DFU 模式 ID 写入 printer.cfg。
  2. 断电后更换可靠的 USB 数据线和上位机 USB 接口，重新上电后再次执行 ls /dev/serial/by-id/*。
  3. 如果使用 Debian 11 Bullseye、旧版 MainsailOS / FluiddPi / Armbian 等系统，执行以下命令查看 udev 版本：
apt-cache policy udev
  1. 如果确认是 Debian 11 的 udev 问题，优先通过系统正常更新源升级 udev，或更换较新的系统镜像。
  2. 检查是否存在可能抢占串口的服务：
systemctl list-units --all | grep -Ei 'ModemManager|brltty'
  1. 如果确认安装了这些服务，并且当前上位机不需要调制解调器或盲文终端功能，可将上一条命令显示的完整单元名替换到命令中，停止并禁用后重启系统：
sudo systemctl disable --now ModemManager.service
sudo systemctl disable --now brltty.service
sudo systemctl disable --now brltty.path
  1. 完成后重新查询 USB ID，并确认 printer.cfg 中 [mcu] 的 serial: 与实际输出一致。

相关配置参考：MCU ID 配置。

Lost communication with MCU​

报错信息：Klipper 与 MCU 通信中断，日志中可能出现 Lost communication with MCU、Lost communication with mcu 或类似提示。

常见场景：归位或移动过程中，限位开关一触发，主板或工具板就掉线；重新上电后又能连接。

常见原因：

  • 限位开关接线错误，触发时造成信号脚与电源或地异常短接。
  • 使用三线限位、光电限位或霍尔限位时，电源、地线、信号线顺序接错。
  • 限位线束破皮、压线或拖链运动时短路。
  • 限位触发瞬间导致主板供电波动，MCU 重启或 USB / CAN 通信中断。
  • MCU 与上位机之间的 USB / CAN 通信线经过强干扰源，触发限位或运动时更容易出现掉线。
  • 配置中的限位引脚与实际接线不一致，触发了错误的接口。

排查方法：

断电操作

拔插限位线、检查线序、检查拖链线束或使用万用表测量通断/电阻前，请完全关闭打印机并断开电源供应。万用表电阻/通断档只能在断电状态使用，禁止通电测电阻或短接测试。

  1. 断电后检查限位开关线序，特别是三线限位的 VCC、GND、Signal 是否接错。
  2. 断电后暂时拔掉对应限位线，重新装好后再上电测试主板是否还会掉线。
  3. 断电后使用万用表通断/电阻档检查限位触发前后是否存在短路，重点检查信号脚是否被接到电源。
  4. 检查拖链、接插件和线束弯折位置，确认触发或移动时不会压线短路。
  5. 检查 MCU 与上位机之间的 USB / CAN 通信线，尽量避开电机线、加热线、热床线和电源线。
  6. 如果机器外壳、电源或屏蔽层未可靠接地，也可能更容易受到干扰；仅确认厂家提供的接地点和插座状态，不要自行拆卸电源或改动市电地线。
  7. 确认配置中的限位引脚与主板文档、实际接线一致。
  8. 问题修复后再执行 QUERY_ENDSTOPS，确认限位状态能正常从 open 变为 TRIGGERED。

相关配置参考：限位相关、电源接线说明。

MCU Protocol error​

报错信息：MCU 协议错误，日志中可能出现 MCU Protocol error、Unknown command 或 Command format mismatch。

Loading...

常见原因：

  • 更新了上位机 Klipper，但没有重新编译并刷写主板或工具板固件。
  • 主板、工具板、EDDY、ADXL 等外设 MCU 的固件版本与上位机 Klipper 不匹配。
  • 使用了定制系统或第三方插件，导致 Klipper 主机端与 MCU 支持的命令不一致。

解决方法：

  1. 确认最近是否更新过 Klipper、系统镜像或插件。
  2. 重新编译并刷写全部 MCU 的 Klipper 固件。
  3. 如果是工具板、EDDY、ADXL 等外设 MCU，请同步更新对应外设固件。
  4. 如果使用定制系统，请确认该系统支持当前 Klipper 版本。
  5. 刷写完成后执行 FIRMWARE_RESTART，再重新连接测试。

专项 FAQ​

专项入口
配置冲突、参数解析、SAVE_CONFIG配置类报错
未知命令、宏模板、切片器起始 G-code配置类报错
运动、归位、限位、探针、网床调平运动、限位与调平报错
温度、加热、挤出、断料检测温度、加热与挤出报错
性能、超时、固件、系统服务系统、性能与服务报错
G2/G3、圆弧拟合、切片器路径精度圆弧拟合建议
TMC 驱动通信、过温、线圈问题TMC 报错排查
CAN 网络、UUID、bytes_invalidCAN 网络与 ID 搜索
加速度计和共振测试加速度计测试与校准
EDDY 涡流探针EDDY 问题合集
Loading...