跳到主要内容

配置类报错

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

homing override method always homes X and Y before homing Z​

报错信息：安全 Z 归位与归位覆盖配置冲突。

Loading...

报错原因：同时配置了 [safe_z_home] 和 [homing_override]，导致 Klipper 无法确认使用哪套归位逻辑。

解决方法：

  1. 在配置文件中搜索 [safe_z_home] 和 [homing_override]。
  2. 根据机器实际归位逻辑只保留其中一项。
  3. 保存并重启 Klipper。

相关配置参考：归位与方向校准指南、归位覆盖参考配置。

Option 'xxx' is not valid in section 'yyy'​

报错信息：Option 'xxx' is not valid in section 'yyy'，指定配置段中存在不被识别的选项名。

常见原因：

  • 选项名拼写错误，例如 sensor_pin 写成了 sensor_ping。
  • 将其他配置段的选项误粘贴到当前段下，例如将 [probe] 的选项写入 [stepper_z]。
  • Klipper 版本升级后，旧版本支持的选项已被移除或重命名。
  • 使用了不是实际参数的注释内容，例如 default_parameter_z。

解决方法：

  1. 仔细检查报错中指出的配置段和选项名，确认拼写。
  2. 参考 Klipper 配置参考文档 确认该选项应属于哪个配置段。
  3. 如果最近升级过 Klipper，查看 配置变更记录 确认选项是否有变动。
  4. 删除或移动到正确配置段中的无效选项。

相关配置参考：配置修改说明。

Section 'xxx' is not a valid config section​

报错信息：Section 'xxx' is not a valid config section、Unknown config object 或某个配置段无法被 Klipper 识别。

常见原因：

  • 配置段名称拼写错误，例如 [bed_mesh] 写成了 [bedmesh]。
  • 当前 Klipper 版本不支持该配置段，或更新/降级后配置格式不兼容。
  • 复制了第三方插件配置，但对应插件、扩展模块或 Klipper 分支没有安装。
  • include 文件中保留了其他机器或其他主板的配置段。

解决方法：

  1. 根据报错中的配置段名称，在 printer.cfg 和所有 include 文件中定位对应段落。
  2. 确认拼写是否与 Klipper 配置参考一致，配置段名称不要使用中文括号或全角符号。
  3. 如果该配置来自第三方插件或定制宏包，确认对应插件已经安装并与当前 Klipper 版本兼容。
  4. 如果不确定该段落用途，先注释该配置段并重启测试，再逐项恢复。

相关配置参考：配置修改说明。

Unable to open config file / Include file does not exist​

报错信息：Unable to open config file /home/xxx/printer_data/config/printer.cfg 或 Include file 'xxx.cfg' does not exist。

常见原因：

  • printer.cfg 文件路径错误或文件被误删。
  • [include] 引用的子配置文件不存在或文件名不匹配。
  • KIAUH 等安装工具自动生成 [include] 引用但对应的 cfg 文件未安装。
  • 权限问题导致 Klipper 无法读取配置文件。

解决方法：

  1. 确认 printer.cfg 是否存在于 Klipper 配置目录，通常为 ~/printer_data/config/printer.cfg。
  2. 检查所有 [include xxx.cfg] 行，确认引用的文件实际存在。
  3. 如果缺少 fluidd.cfg 或 mainsail.cfg，参考对应 Web 界面的安装文档补充配置。
  4. 确保配置文件权限正确：ls -la ~/printer_data/config/。

Unable to parse option / option must be specified​

报错信息：Unable to parse option 'xxx' in section 'yyy'、Option 'xxx' in section 'yyy' must be specified，或 must have minimum/maximum、must be above/below。

常见原因：

  • 必填参数缺失，例如 [extruder] 缺少 step_pin、dir_pin、heater_pin 或 sensor_type。
  • 参数格式错误，例如需要数字却填了文字，需要坐标列表却少了逗号。
  • 参数值超出 Klipper 允许范围，例如 run_current、max_temp、position_max 设置不合理。
  • 复制配置时保留了中文标点、全角符号或不可见字符。

解决方法：

  1. 根据报错中的配置段和参数名，回到对应 .cfg 文件逐项检查。
  2. 对数字、坐标和列表参数，确认格式与示例一致，例如 mesh_min: 20, 20。
  3. 对 must be above/below 或 minimum/maximum，先恢复为官方示例或主板教程推荐值。
  4. 保存后执行 RESTART，若仍失败，再查看 klippy.log 中第一条配置报错。

相关配置参考：配置修改说明。

Unknown pin chip name / pin used multiple times​

报错信息：Unknown pin chip name 'xxx'、Invalid pin description 'xxx'、pin xxx used multiple times in config。

常见原因：

  • 多 MCU 配置中引脚前缀写错，例如应写 EBBCan:PB0 却写成了不存在的 MCU 名称。
  • 引脚名拼写错误，或将主板教程中的引脚直接复制到另一块主板。
  • 同一个物理引脚被多个功能重复占用，例如风扇、加热器、限位同时用了同一引脚。
  • 引脚反相 !、上拉 ^、下拉 ~ 写在了错误位置。

解决方法：

  1. 检查 [mcu xxx] 的名称是否与引脚前缀完全一致，大小写也要一致。
  2. 对照主板引脚图，确认每个 pin:、step_pin:、dir_pin:、heater_pin: 都属于当前主板。
  3. 在所有 include 文件中搜索报错引脚，删除或更换重复占用项。
  4. 引脚修饰符应写在引脚名前，例如 ^PB7、!PC13、mcu2:^PB7。

相关配置参考：配置修改说明、风扇参考配置。

gcode command XXX already registered​

报错信息：Error: gcode command XXX already registered。

报错原因：两个不同的宏或系统模块注册了相同的 G-code 命令名，例如两个宏都定义了 [gcode_macro NEXT]。

常见场景：

  • 用户自定义宏与 Klipper 系统模块或第三方配置冲突。
  • 多个 [gcode_macro M600] 定义。

解决方法：

  1. 在 printer.cfg 及所有 [include] 文件中搜索重复定义。
  2. 删除或重命名冲突的 [gcode_macro]。
  3. 检查 [homing_override]、[gcode_macro PAUSE]、[gcode_macro RESUME]、[gcode_macro CANCEL_PRINT] 等常用宏。

相关配置参考：宏介绍。

Unknown command:"XXX"​

报错信息：控制台或 klippy.log 中出现 Unknown command:"PRINT_START"、Unknown command:"START_PRINT"、Unknown command:"M600"、Unknown command:"EXCLUDE_OBJECT_START"、Unknown command:"EXCLUDE_OBJECT_END"、Unknown command:"M106"、Unknown command:"M201"、Unknown command:"M203"、Unknown command:"M205" 等。

常见原因：

  • 切片器起始或结束 G-code 调用了 Klipper 中不存在的宏，例如切片器发送 PRINT_START，但配置中只定义了 [gcode_macro START_PRINT]。
  • 使用了从 Marlin 迁移来的命令，Klipper 默认不支持或需要用宏兼容。
  • 启用了排除对象功能，但切片器、Moonraker 或 Klipper 配置不完整，导致 EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END 无法识别。
  • 风扇使用了 [fan_generic] 或 [output_pin]，但切片器仍发送默认 M106 / M107。
  • 使用第三方宏包时缺少 include 文件，或宏名称与切片器中填写的名称不一致。

解决方法：

  1. 在 printer.cfg 和所有 include 文件中搜索报错里的命令名，确认是否存在对应 [gcode_macro XXX]。
  2. 让切片器中的起始、结束、换料、风扇和排除对象命令名称与 Klipper 宏保持一致。
  3. 如果是 Marlin 命令，优先删除不需要的命令；确实需要兼容时，再添加明确的 Klipper 宏。
  4. 排除对象相关报错应同时检查切片器是否输出对象标签、Moonraker 是否启用对象处理、Klipper 是否有 [exclude_object]。
  5. 风扇命令报错时，确认是否应使用 [fan]，或为 [fan_generic] / [output_pin] 添加匹配的控制宏。

相关配置参考：宏介绍、配置修改说明。

Error evaluating 'gcode_macro XXX:gcode'​

报错信息：Error evaluating 'gcode_macro PRINT_START:gcode'、jinja2.exceptions.UndefinedError、'dict object' has no attribute 'BED'、'dict object' has no attribute 'HOTEND'、'dict object' has no attribute 'extrude'、'dict object' has no attribute 'heater_bed'、gcode.CommandError。

常见原因：

  • 切片器没有传入宏需要的参数，例如宏中读取 params.HOTEND，但切片器没有传 HOTEND=。
  • 参数名不一致，例如宏需要 BED / HOTEND，切片器实际传入 BED_TEMP / EXTRUDER_TEMP。
  • 宏引用了不存在的对象，例如配置中没有 [heater_bed]，但宏读取了 printer.heater_bed。
  • 宏中使用了 Jinja2 语法，但括号、引号、过滤器或默认值写法错误。
  • 宏内部执行的命令先报错，外层只显示为 Error evaluating。

解决方法：

  1. 查看 klippy.log 中 Error evaluating 下方的完整 Traceback，确认是哪个变量或命令出错。
  2. 对照切片器起始 G-code，确认传入参数名称与宏中 params.xxx 完全一致，大小写也要一致。
  3. 给可选参数设置默认值，例如 params.BED|default(60)|float，避免参数为空时报错。
  4. 搜索宏中使用的 printer.xxx 对象，确认配置里存在对应模块。
  5. 如果宏来自第三方配置包，确认所有依赖 include 文件和基础宏都已加载。

相关配置参考：宏介绍。

SAVE_CONFIG 失败或配置冲突​

报错信息：执行 SAVE_CONFIG 后提示 Unable to write config、Option conflict、Cannot save config，或保存后打印机无法启动。

常见原因：

  • printer.cfg 文件权限不足，Klipper 进程无法写入，常见于使用 sudo 编辑过配置文件后。
  • 自动保存区（#*# 标记块）中的配置项与手动 [include] 文件中相同选项冲突。
  • MCU 已处于 shutdown 状态，SAVE_CONFIG 无法正常下发新配置。
  • printer.cfg 文件末尾存在语法错误或被截断，导致自动保存区写入失败。
  • 多个 include 文件重复定义了不应由 SAVE_CONFIG 自动保存的参数，如 PID、Z offset。

解决方法：

  1. 确认配置文件权限：

    ls -la ~/printer_data/config/printer.cfg

    如果属主不是当前用户，执行：sudo chown $USER:$USER ~/printer_data/config/printer.cfg

  2. 如果 SAVE_CONFIG 后打印机无法启动，打开 printer.cfg 底部查看 #*# 自动保存区。

  3. 如果同一选项在 include 文件中也存在，删除自动保存区中的重复项，或改为在 include 文件中统一管理。

  4. 如果 MCU 处于 shutdown 状态，先执行 FIRMWARE_RESTART，再重新执行 SAVE_CONFIG。

  5. 如果权限正常但仍无法写入，检查磁盘空间：df -h ~/printer_data/。

相关配置参考：配置修改说明。

Loading...