Skip to main content

Configuration Class Errors

This page consolidates configuration section conflicts, parameter spelling, include files, and SAVE_CONFIG related issues. After modifying the configuration, please first check the first configuration error in klippy.log, then address each item consecutively.

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

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

Loading...

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 of them based on the machine's actual homing logic.
  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 in the specified configuration section.

Common Causes:

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

Solution:

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

Related configuration reference: Configuration Modification Instructions.

Section 'xxx' is not a valid config section​

Error Message: Section 'xxx' is not a valid config section, Unknown config object, or a configuration 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 configuration format is incompatible after an update/downgrade.
  • Copied a third-party plugin configuration, but the corresponding plugin, extension module, or Klipper branch is not installed.
  • Include files retain configuration sections from other machines or motherboards.

Solution:

  1. Based on the section name in the error, locate the corresponding paragraph in printer.cfg and all include files.
  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 purpose of the paragraph, comment it out and restart for testing, then restore items one by one.

Related configuration reference: Configuration Modification Instructions.

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 filename 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 confirm 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., text entered when a number is required, missing commas for coordinate lists.
  • Parameter value is outside the allowed range for Klipper, e.g., unreasonable run_current, max_temp, or position_max settings.
  • Copying configuration retained Chinese punctuation, full-width symbols, or invisible characters.

Solution:

  1. Based on the configuration 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 examples, e.g., mesh_min: 20, 20.
  3. For must be above/below or minimum/maximum errors, first restore the official example or motherboard tutorial recommended values.
  4. Save and execute RESTART. If it still fails, check the first configuration error in klippy.log.

Related configuration reference: Configuration Modification Instructions.

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 multi-MCU configurations, the pin prefix is misspelled, e.g., writing EBBCan:PB0 as a non-existent MCU name.
  • Pin name is misspelled, or pins were directly copied from a motherboard tutorial to another board.
  • The same physical pin is occupied by multiple functions, e.g., fan, heater, and endstop all using the same pin.
  • Pin inversion !, pullup ^, or pulldown ~ is written in the wrong position.

Solution:

  1. Check that the name of [mcu xxx] exactly matches the pin prefix, including case sensitivity.
  2. Refer to the motherboard pinout diagram to confirm each pin:, step_pin:, dir_pin:, and heater_pin: belongs to the current motherboard.
  3. Search for the error pin in all include files and remove or change the duplicate entry.
  4. Pin modifiers should be written before the pin name, e.g., ^PB7, !PC13, mcu2:^PB7.

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

gcode command XXX already registered​

Error Message: Error: gcode command XXX already registered.

Cause: Two different macros or system modules have registered 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 [gcode_macro M600] definitions exist.

Solution:

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

Related configuration reference: Macros Introduction.

SAVE_CONFIG fails or configuration conflicts​

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

Common Causes:

  • Insufficient permissions for the printer.cfg file, preventing the Klipper process from writing, often after editing the configuration file with sudo.
  • Configuration items in the auto-save area (#*# marked block) conflict with the same options in a manually included [include] file.
  • The MCU is in a shutdown state, so SAVE_CONFIG cannot properly submit new configurations.
  • There are syntax errors or truncation at the end of the printer.cfg file, causing the auto-save area to fail writing.
  • Multiple include files repeatedly define parameters that should not be auto-saved 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, execute FIRMWARE_RESTART first, 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 Instructions.

Loading...