Skip to main content

Config Class Errors

This page collects issues related to config section conflicts, parameter spelling, include files, and SAVE_CONFIG. After modifying configurations, first check the first configuration error in klippy.log, then address them one by one.

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

Error Message: Safe Z homing conflicts with homing override configuration.

Loading...

Root Cause: Both [safe_z_home] and [homing_override] are configured, causing Klipper to be unable to determine which homing logic to use.

Solution:

  1. Search for [safe_z_home] and [homing_override] in the configuration file.
  2. Keep only one based on the actual homing logic of the machine.
  3. Save and restart Klipper.

Related configuration reference: Homing and Direction Calibration Guide, Homing Override Reference Configuration.

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

Error Message: Option 'xxx' is not valid in section 'yyy', indicating an unrecognized option name exists in the specified config section.

Common Causes:

  • Misspelled option name, e.g., sensor_pin written as sensor_ping.
  • Options from another section mistakenly pasted into the current one, e.g., [probe] options written in [stepper_z].
  • After a Klipper version upgrade, options supported in the old version have been removed or renamed.
  • Comment content that is not an actual parameter, e.g., default_parameter_z.

Solution:

  1. Carefully check the config section and option name indicated in the error to confirm spelling.
  2. Refer to the Klipper Configuration Reference to confirm which section the option belongs to.
  3. If Klipper was recently upgraded, check the Configuration Changes to see if the option has changed.
  4. Delete invalid options or move them to the correct config section.

Related configuration reference: Configuration Modification Guide.

Section 'xxx' is not a valid config section​

Error Message: Section 'xxx' is not a valid config section, Unknown config object, or a config section cannot be recognized by Klipper.

Common Causes:

  • Misspelled section name, e.g., [bed_mesh] written as [bedmesh].
  • The current Klipper version does not support this section, or the config format is incompatible after an update/downgrade.
  • A third-party plugin configuration is copied, but the corresponding plugin, extension module, or Klipper branch is not installed.
  • Include files retain sections meant for another machine or motherboard.

Solution:

  1. Locate the corresponding section in printer.cfg and all include files based on the section name in the error.
  2. Confirm the spelling matches the Klipper configuration reference; do not use Chinese brackets or full-width symbols for section names.
  3. If the configuration comes from a third-party plugin or custom macro package, confirm the corresponding plugin is installed and compatible with the current Klipper version.
  4. If unsure about the section's purpose, comment it out, restart, and test, then restore items one by one.

Related configuration reference: Configuration Modification Guide.

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

Error Message: Unable to open config file /home/xxx/printer_data/config/printer.cfg or Include file 'xxx.cfg' does not exist.

Common Causes:

  • The printer.cfg file path is incorrect or the file has been accidentally deleted.
  • The sub-configuration file referenced by [include] does not exist or the file name does not match.
  • Installation tools like KIAUH automatically generate [include] references, but the corresponding cfg file is not installed.
  • Permission issues prevent Klipper from reading the configuration file.

Solution:

  1. Confirm that printer.cfg exists in the Klipper configuration directory, usually ~/printer_data/config/printer.cfg.
  2. Check all [include xxx.cfg] lines to ensure the referenced files actually exist.
  3. If fluidd.cfg or mainsail.cfg is missing, refer to the corresponding Web interface installation documentation to add the configuration.
  4. Ensure configuration file permissions are correct: ls -la ~/printer_data/config/.

Unable to parse option / option must be specified​

Error Message: Unable to parse option 'xxx' in section 'yyy', Option 'xxx' in section 'yyy' must be specified, or must have minimum/maximum, must be above/below.

Common Causes:

  • Required parameters are missing, e.g., [extruder] missing step_pin, dir_pin, heater_pin, or sensor_type.
  • Parameter format is incorrect, e.g., requiring a number but providing text, or requiring a coordinate list but missing a comma.
  • Parameter value exceeds Klipper's allowed range, e.g., unreasonable run_current, max_temp, or position_max settings.
  • Chinese punctuation, full-width symbols, or invisible characters are retained when copying configuration.

Solution:

  1. According to the config section and parameter name in the error, go back to the corresponding .cfg file and check each item.
  2. For numbers, coordinates, and list parameters, confirm the format matches the example, e.g., mesh_min: 20, 20.
  3. For must be above/below or minimum/maximum, first revert to the official example or values recommended by the motherboard tutorial.
  4. After saving, execute RESTART. If it still fails, check the first configuration error in klippy.log.

Related configuration reference: Configuration Modification Guide.

Unknown pin chip name / pin used multiple times​

Error Message: Unknown pin chip name 'xxx', Invalid pin description 'xxx', pin xxx used multiple times in config.

Common Causes:

  • In a multi-MCU configuration, the pin prefix is incorrect, e.g., should write EBBCan:PB0 but wrote a non-existent MCU name.
  • Pin name spelling error, or directly copying pins from one motherboard's tutorial to another.
  • The same physical pin is used by multiple functions, e.g., fan, heater, and endstop all using the same pin.
  • Pin inversion !, pull-up ^, pull-down ~ are written in the wrong position.

Solution:

  1. Check if the name in [mcu xxx] is exactly the same as the pin prefix, including case sensitivity.
  2. Compare with the motherboard pinout diagram to confirm each pin:, step_pin:, dir_pin:, heater_pin: belongs to the current motherboard.
  3. Search for the error pin in all include files, delete or replace duplicate entries.
  4. Pin modifiers should be written before the pin name, e.g., ^PB7, !PC13, mcu2:^PB7.

Related configuration reference: Configuration Modification Guide, Fan Reference Configuration.

gcode command XXX already registered​

Error Message: Error: gcode command XXX already registered.

Root Cause: Two different macros or system modules register the same G-code command name, e.g., both macros define [gcode_macro NEXT].

Common Scenarios:

  • User-defined macros conflict with Klipper system modules or third-party configurations.
  • Multiple definitions of [gcode_macro M600].

Solution:

  1. Search for duplicate definitions in printer.cfg and all [include] files.
  2. Delete or rename conflicting [gcode_macro].
  3. Check commonly used macros like [homing_override], [gcode_macro PAUSE], [gcode_macro RESUME], [gcode_macro CANCEL_PRINT].

Related configuration reference: Macros Introduction.

Unknown command:"XXX"​

Error Message: In the console or klippy.log, occurrences like 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".

Common Causes:

  • The slicer's start or end G-code calls a macro that does not exist in Klipper, e.g., the slicer sends PRINT_START, but the configuration only defines [gcode_macro START_PRINT].
  • Commands migrated from Marlin are used, which Klipper does not support by default or requires macros to be compatible.
  • The exclude object function is enabled, but the slicer, Moonraker, or Klipper configuration is incomplete, causing EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END to be unrecognized.
  • Fans use [fan_generic] or [output_pin], but the slicer still sends default M106 / M107.
  • When using third-party macro packages, include files are missing, or macro names don't match the names filled in the slicer.

Solution:

  1. Search for the command name in the error within printer.cfg and all include files to confirm if the corresponding [gcode_macro XXX] exists.
  2. Ensure the names of start, end, filament change, fan, and exclude object commands in the slicer match the Klipper macros.
  3. For Marlin commands, prioritize deleting unnecessary ones; if compatibility is genuinely needed, add explicit Klipper macros.
  4. For exclude object related errors, simultaneously check if the slicer outputs object labels, if Moonraker has object processing enabled, and if Klipper has [exclude_object].
  5. For fan command errors, confirm whether [fan] should be used, or add matching control macros for [fan_generic] / [output_pin].

Related configuration reference: Macros Introduction, Configuration Modification Guide.

Error evaluating 'gcode_macro XXX:gcode'​

Error Message: 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.

Common Causes:

  • The slicer does not pass the parameters required by the macro, e.g., the macro reads params.HOTEND, but the slicer does not pass HOTEND=.
  • Parameter names are inconsistent, e.g., the macro needs BED / HOTEND, but the slicer actually passes BED_TEMP / EXTRUDER_TEMP.
  • The macro references a non-existent object, e.g., there is no [heater_bed] in the configuration, but the macro reads printer.heater_bed.
  • Jinja2 syntax is used in the macro, but the parentheses, quotes, filters, or default values are written incorrectly.
  • A command executed within the macro errors first, and the outer layer only shows Error evaluating.

Solution:

  1. View the full Traceback below Error evaluating in klippy.log to confirm which variable or command is causing the error.
  2. Compare with the slicer's start G-code to confirm the parameter names passed in exactly match params.xxx in the macro, including case sensitivity.
  3. Set default values for optional parameters, e.g., params.BED|default(60)|float, to avoid errors when parameters are empty.
  4. Search for printer.xxx objects used in the macro to confirm the corresponding modules exist in the configuration.
  5. If the macro comes from a third-party configuration package, confirm all dependent include files and base macros are loaded.

Related configuration reference: Macros Introduction.

SAVE_CONFIG failure or configuration conflict​

Error Message: After executing SAVE_CONFIG, prompts like Unable to write config, Option conflict, Cannot save config, or the printer fails to start after saving.

Common Causes:

  • printer.cfg file permissions are insufficient, and the Klipper process cannot write, commonly after editing the configuration file using sudo.
  • Configuration items in the auto-save area (#*# marked block) conflict with the same options in manual [include] files.
  • The MCU is already in a shutdown state, preventing SAVE_CONFIG from properly issuing new configurations.
  • Syntax errors or truncation at the end of the printer.cfg file cause the auto-save area to fail to write.
  • Multiple include files redundantly define parameters that should not be saved automatically by SAVE_CONFIG, such as PID, Z offset.

Solution:

  1. Confirm configuration file permissions:

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

    If the owner is not the current user, execute: sudo chown $USER:$USER ~/printer_data/config/printer.cfg

  2. If the printer fails to start after SAVE_CONFIG, open printer.cfg and check the #*# auto-save area at the bottom.

  3. If the same option also exists in an include file, delete the duplicate item in the auto-save area, or manage it uniformly in the include file.

  4. If the MCU is in a shutdown state, first execute FIRMWARE_RESTART, then re-execute SAVE_CONFIG.

  5. If permissions are normal but writing still fails, check disk space: df -h ~/printer_data/.

Related configuration reference: Configuration Modification Guide.

Loading...