04 常见问题与排障

📄️常见报错总览

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

本文档收录常见硬件模块的最小化测试方法，用于在排障时隔离单个硬件，确认问题来自配置、线束、模块本体还是主板端口。

本页用于集中说明 Klipper 中主板、工具板、CAN 设备和上位机 MCU 的 ID 填写规则。配置连接类问题时，请先确认通信方式，再填写对应的 serial。

本文用于验证步进驱动、CAN 工具板等外设模块是否正常工作。测试思路与基础 I/O 测试一致，使用最小化 Klipper 配置隔离单个硬件。

本页集中整理配置段冲突、参数拼写、include 文件和 SAVE_CONFIG 相关问题。修改配置后请先看 klippy.log 中第一条配置错误，再逐项处理。

技术背景

本页整理移动范围、归位、限位、探针、网床和多 Z 调平相关报错。涉及接线、插头、手动机械调整时，请先断电再操作。

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

依赖包安装

本页整理归位通信超时、MCU 定时错误、上位机性能、固件刷写和 Klipper 服务启动相关问题。

本文用于处理 CAN 网络配置、CAN0 状态确认、CAN UUID 搜索以及常见 CAN 报错排查。

本文用于处理 CAN 网络常见报错、通信异常排查以及搜索不到 CAN ID 时的排查流程。

本文用于说明 Klipper 中 [gcode_arcs]、G2 / G3 圆弧指令和切片器圆弧拟合的取舍。日常 3D 打印不建议把 Klipper 端圆弧拟合作为提升质量或性能的主要方案。

问题描述

本页整理 Input Shaper（共振补偿）和 Pressure Advance（压力提前）相关的配置错误与调优异常。加速度计硬件连接与通信报错请参考加速度计测试与校准。

归位时报错 Error during homing z: Eddy current sensor error

本页面用于 EDDY 在 TAP 模式下的调试流程、检查顺序和常见问题排查。TAP 模式通过喷嘴轻触床面判断触发阈值，调试时需留意喷嘴、热床和 Z 轴运动状态。

本页用于排查外置驱动配置后出现的不转、只单向转、振动、丢步、模型倾斜和 5V 升压模块异常等问题。

常用 Klipper 控制台调试命令已统一维护到参考配置目录，避免 FAQ 与配置参考出现重复内容。

本文用于记录 Klipper loadcell / loadcell_probe 相关关键词和基础排查方向。Load Cell 探针仍属于相对新的方案，普通用户不要按零散社区配置自行改装压力传感器；请优先使用产品文档、官方 Klipper 文档或厂家提供的完整配置。

bltouch-guide}

本文说明 FLY-EDDY 系列（EDDY-M / EDDY-F）传感器的 I2C 引脚定义、两种连接方式的引脚对照与接线步骤，以及 probeeddycurrent 所需的 I2C 相关配置项。

适用于使用 RP2040 主控的 FLY 工具板（FLY-SHT36、FLY-SB2040、FLY-MMU 等）在自行编译 Katapult / Klipper 固件后出现不启动、启动不稳定问题时的修复方法。出厂固件由厂家提供，仅在自行编译固件遇到问题时才需要参考本页。