跳到主要内容

配置类报错

本页集中整理配置段冲突、参数拼写、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/。

Fluidd / Mainsail 基础配置缺失​

报错信息：Fluidd 或 Mainsail 提示基础配置缺失，常见关键词包括：

[virtual_sdcard] not found in printer configuration.
[pause_resume] not found in printer configuration.
[display_status] is required if you do not have a [display] defined.
CANCEL_PRINT macro not found in configuration.

Fluidd 提示示例：

Loading...

Mainsail 提示示例：

Loading...

常见原因：

  • printer.cfg 没有启用 [include fluidd.cfg] 或 [include mainsail.cfg]。
  • 配置目录中缺少 fluidd.cfg / mainsail.cfg，或 include 文件名写错。
  • 手动配置时漏写 [virtual_sdcard]、[pause_resume]、[display_status]。
  • 没有定义 CANCEL_PRINT 宏，或宏文件没有被 include。

解决方法：

  1. 必须优先使用默认前端配置文件，不建议普通用户只手动补几个配置段来绕过提示。默认 fluidd.cfg / mainsail.cfg 会同时提供虚拟 SD 卡、暂停恢复、显示状态和取消打印宏等前端需要的基础配置。

  2. 确认 printer.cfg 顶部是否包含当前使用前端对应的 include：

    [include fluidd.cfg]

    或：

    [include mainsail.cfg]

  3. 如果使用 FLY 预置系统或官方参考配置，确认 fluidd.cfg / mainsail.cfg 文件存在于 ~/printer_data/config/ 目录。

  4. 如果对应文件不存在，请重新补充前端默认配置文件，或参考 Fluidd 初始配置说明。

  5. 启用默认前端配置文件后，如需修改暂停、恢复、取消打印的位置和回抽参数，再按 暂停与取消打印自定义位置 添加 _CLIENT_VARIABLE，不要直接复制或改写默认 CANCEL_PRINT / PAUSE / RESUME 宏。

  6. 只有在维护自定义系统、且明确知道前端宏依赖关系时，才考虑手动补齐基础段。此方式不推荐普通用户使用，至少需要包含：

    [virtual_sdcard]
    path: ~/printer_data/gcodes
    on_error_gcode: CANCEL_PRINT

    [pause_resume]

    [display_status]

    同时还必须提供可用的 [gcode_macro CANCEL_PRINT]，否则前端仍会提示 CANCEL_PRINT macro not found in configuration。

  7. 保存配置后执行 RESTART。若仍提示缺失，继续检查所有 include 文件是否真正被 Klipper 读取。

前端宏使用方法：暂停与取消打印自定义位置 宏配置参考：宏介绍

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 is not a valid pin name / pin used multiple times​

报错信息：Unknown pin chip name 'xxx'、Pin 'PB12' is not a valid pin name on mcu 'mcu'、Invalid pin description 'xxx'、pin xxx used multiple times in config。

常见原因：

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

解决方法：

  1. 检查 [mcu xxx] 的名称是否与引脚前缀完全一致，大小写也要一致。
  2. 核对 [mcu xxx] 段的 canbus_uuid 或 serial 是否与实际设备匹配（可用 ls /dev/serial/by-id/ 或 python3 -c "import can; ..." 确认）。
  3. 对照主板引脚图，确认每个 pin:、step_pin:、dir_pin:、heater_pin: 都属于当前主板。
  4. 在所有 include 文件中搜索报错引脚，删除或更换重复占用项。
  5. 引脚修饰符应写在引脚名前，例如 ^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_DEFINE"、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_DEFINE、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] 添加匹配的控制宏。

EXCLUDE_OBJECT_DEFINE / START / END​

报错含义：EXCLUDE_OBJECT_DEFINE 用于定义打印对象，EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END 用于标记当前 G-code 属于哪个对象，前端才能在多对象打印时显示并排除指定对象。如果 klippy.log 反复出现 Unknown command:"EXCLUDE_OBJECT_DEFINE"、Unknown command:"EXCLUDE_OBJECT_START" 或 Unknown command:"EXCLUDE_OBJECT_END"，说明 G-code 中已经包含对象排除命令，但 Klipper 当前配置没有正确接收这类命令。

优先检查：

  1. 在 printer.cfg 或被 include 的配置文件中确认存在：
[exclude_object]
  1. 修改后执行 RESTART，再重新上传 G-code 文件测试。已经上传过的旧文件可能没有经过最新配置处理，建议重新切片或重新上传。
  2. 检查 Moonraker 配置是否启用对象处理，常见配置位置为 moonraker.conf：
[file_manager]
enable_object_processing: True
  1. 检查切片器是否开启对象标签 / 排除对象相关输出。不同切片器名称不同，常见表现是 G-code 中能搜索到 EXCLUDE_OBJECT_DEFINE、EXCLUDE_OBJECT_START、EXCLUDE_OBJECT_END 或对象名称。
  2. 如果只想临时完成打印、不需要对象排除功能，可以在切片器中关闭对象排除相关输出后重新切片；不要只删除文件中的部分对象命令，否则前端对象列表可能异常。

判断方向：

  • 只报 EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END：优先补 [exclude_object]，然后重启 Klipper。
  • 前端没有对象列表，但 Klipper 不再报 Unknown command：优先检查 Moonraker 的对象处理和 G-code 是否重新上传。
  • 文件中完全搜不到对象相关命令：说明切片器没有输出对象标签，需要在切片器侧启用。

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

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/。

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

SDCARD_RESET_FILE cannot be run from the sdcard​

报错信息：SDCARD_RESET_FILE cannot be run from the sdcard。

常见原因：

  • 在 SD 卡打印过程中执行了 SDCARD_RESET_FILE 命令，该命令不允许在 SD 卡打印期间调用。
  • 切片器起始 G-code 或宏中误包含了 SDCARD_RESET_FILE。

解决方法：

  1. 检查切片器起始 G-code 和自定义宏，删除或注释掉 SDCARD_RESET_FILE 调用。
  2. 如果确实需要重置 SD 卡文件状态，在打印结束后手动执行，不要放在打印流程中。
  3. 如果使用 PRINT_START 宏，确认其中没有调用此命令。
Loading...