Skip to main content

Configuration Class Errors

This page compiles issues related to configuration section conflicts, parameter spelling, include files, and SAVE_CONFIG problems. After modifying the configuration, 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...

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 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 in the specified configuration section.

Common Causes:

  • Spelling error in the option name, e.g., sensor_pin written as sensor_ping.
  • Options from another configuration section pasted incorrectly under the current section, e.g., writing a [probe] option under [stepper_z].
  • After a Klipper version upgrade, options supported in the older version have been removed or renamed.
  • Using comment content that is not an actual parameter, 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 Klipper was recently upgraded, check the Configuration Changes to see if the option has changed.
  4. Delete the invalid option or move it 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:

  • Spelling error in the configuration section name, e.g., [bed_mesh] written as [bedmesh].
  • The current Klipper version does not support this configuration 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.
  • The include file retains configuration sections from another machine or motherboard.

Solution:

  1. Based on the configuration 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 configuration 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 out the configuration section first and restart for testing, then restore them 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 was accidentally deleted.
  • The sub-configuration file referenced by [include] does not exist or the filename does not match.
  • Installation tools like KIAUH automatically generated [include] references, but the corresponding cfg files were not installed.
  • Permission issues prevent Klipper from reading the configuration file.

Solution:

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

Fluidd / Mainsail Basic Configuration Missing​

Error Message: Fluidd or Mainsail indicates basic configuration is missing. Common keywords include:

[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 prompt example:

Loading...

Mainsail prompt example:

Loading...

Common Causes:

  • [include fluidd.cfg] or [include mainsail.cfg] is not enabled in printer.cfg.
  • fluidd.cfg / mainsail.cfg is missing from the configuration directory, or the include filename is misspelled.
  • [virtual_sdcard], [pause_resume], [display_status] were omitted during manual configuration.
  • The CANCEL_PRINT macro is not defined, or the macro file is not included.

Solution:

  1. Must prioritize using the default frontend configuration file. It is not recommended for general users to bypass the prompting by manually adding only a few configuration sections. The default fluidd.cfg / mainsail.cfg will simultaneously provide the basic configurations needed by the frontend, such as virtual SD card, pause/resume, display status, and cancel print macros.

  2. Confirm that printer.cfg includes the include corresponding to the currently used frontend at the top:

    [include fluidd.cfg]

    or:

    [include mainsail.cfg]

  3. If using a FLY preset system or official reference configuration, confirm that the fluidd.cfg / mainsail.cfg files exist in the ~/printer_data/config/ directory.

  4. If the corresponding files do not exist, re-supplement the default frontend configuration file, or refer to the Fluidd Initial Setup Instructions.

  5. After enabling the default frontend configuration file, if you need to modify the position and retraction parameters for pause, resume, and cancel print, then add _CLIENT_VARIABLE according to the Custom Pause and Cancel Print Positions. Do not directly copy or rewrite the default CANCEL_PRINT / PAUSE / RESUME macros.

  6. Only consider manually supplementing the basic sections when maintaining a custom system and you clearly know the frontend macro dependency relationships. This method is not recommended for general users. It must at least include:

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

    [pause_resume]

    [display_status]

    A functional [gcode_macro CANCEL_PRINT] must also be provided, otherwise the frontend will still prompt CANCEL_PRINT macro not found in configuration.

  7. Save the configuration and execute RESTART. If it still prompts missing, continue to check if all include files are actually being read by Klipper.

Frontend Macro Usage Method: Custom Pause and Cancel Print Positions Macro Configuration Reference: Macro Introduction

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 parameter is missing, e.g., [extruder] missing step_pin, dir_pin, heater_pin, or sensor_type.
  • Parameter format is incorrect, e.g., requiring a number but text was entered, or requiring a coordinate list but a comma is missing.
  • Parameter value is outside the allowed range for Klipper, e.g., unreasonable settings for run_current, max_temp, position_max.
  • Retained Chinese punctuation, full-width symbols, or invisible characters when copying configuration.

Solution:

  1. Based on the configuration section and parameter name in the error, go back to the corresponding .cfg file and check item by 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 restore to the official example or the value recommended by the motherboard tutorial.
  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 is not a valid pin name / Pin used multiple times​

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

Common Causes:

  • The pin prefix is wrong in a multi-MCU configuration, e.g., should be toolboard:PB0 but written as a non-existent MCU name.
  • The MCU ID (canbus_uuid or serial) is configured incorrectly, causing pin mapping to the wrong device which does not have the corresponding pin.
  • Spelling error in the pin name, or directly copying a pin from a motherboard tutorial to a different motherboard.
  • The same physical pin is occupied by multiple functions, e.g., fan, heater, endstop using the same pin.
  • Pin inversion !, pull-up ^, pull-down ~ are written in the wrong position.

Solution:

  1. Check if the name of [mcu xxx] exactly matches the pin prefix, including case sensitivity.
  2. Verify that the canbus_uuid or serial of the [mcu xxx] section matches the actual device (can be confirmed using ls /dev/serial/by-id/ or python3 -c "import can; ...").
  3. Compare with the motherboard pinout diagram to confirm that each pin:, step_pin:, dir_pin:, heater_pin: belongs to the current motherboard.
  4. Search for the error-reported pin in all include files, and delete or change the duplicate occupancy item.
  5. Pin modifiers should be written before the pin name, e.g., ^PB7, !PC13, mcu2:^PB7.

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

G-code command XXX already registered​

Error Message: Error: gcode command XXX already registered.

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

Common Scenarios:

  • User-defined macro conflicts 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 the conflicting [gcode_macro].
  3. Check common macros such as [homing_override], [gcode_macro PAUSE], [gcode_macro RESUME], [gcode_macro CANCEL_PRINT].

Related configuration reference: Macro Introduction.

Unknown command:"XXX"​

Error Message: 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" appearing in the console or klippy.log.

Common Causes:

  • The slicer's start or end G-code calls a macro that doesn't exist in Klipper, e.g., the slicer sends PRINT_START, but only [gcode_macro START_PRINT] is defined.
  • Used commands migrated from Marlin, which Klipper does not support by default or needs a macro for compatibility.
  • Exclude object functionality is enabled, but the slicer, Moonraker, or Klipper configuration is incomplete, causing commands like EXCLUDE_OBJECT_DEFINE, EXCLUDE_OBJECT_START, EXCLUDE_OBJECT_END to be unrecognized.
  • The fan uses [fan_generic] or [output_pin], but the slicer still sends default M106 / M107.
  • Missing include files for a third-party macro package, or the macro name is inconsistent with the name written in the slicer.

Solution:

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

EXCLUDE_OBJECT_DEFINE / START / END​

Error Meaning: EXCLUDE_OBJECT_DEFINE is used to define a print object, EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END is used to mark which object the current G-code belongs to, so the frontend can display and exclude specific objects during multi-object printing. If klippy.log repeatedly shows Unknown command:"EXCLUDE_OBJECT_DEFINE", Unknown command:"EXCLUDE_OBJECT_START", or Unknown command:"EXCLUDE_OBJECT_END", it means the G-code already contains object exclusion commands, but the current Klipper configuration is not correctly handling these commands.

Priority Checks:

  1. Confirm the presence of the following in printer.cfg or a configuration file that is included:
[exclude_object]
  1. After modification, execute RESTART, then re-upload the G-code file for testing. Old files that have already been uploaded may not have been processed with the latest configuration. It is recommended to re-slice or re-upload.
  2. Check if Moonraker configuration enables object processing. Common configuration location is moonraker.conf:
[file_manager]
enable_object_processing: True
  1. Check if the slicer has enabled output for object labels / exclude objects. The names vary by slicer, but a common indication is the presence of EXCLUDE_OBJECT_DEFINE, EXCLUDE_OBJECT_START, EXCLUDE_OBJECT_END, or object names in the G-code.
  2. If the goal is just to temporarily complete a print without needing object exclusion, disable the object exclusion related output in the slicer and re-slice; do not just delete some object commands from the file, as this may cause anomalies in the frontend object list.

Guidance for Diagnosis:

  • Only reports EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END: Prioritize adding [exclude_object], then restart Klipper.
  • Frontend has no object list, but Klipper no longer reports Unknown command: Prioritize checking Moonraker's object processing and whether the G-code was re-uploaded.
  • Cannot find object-related commands at all in the file: Indicates the slicer did not output object labels. Enable this in the slicer settings.

Related configuration reference: Macro Introduction, Configuration Modification Instructions.

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 did not pass parameters required by the macro, e.g., the macro reads params.HOTEND, but the slicer does not pass HOTEND=.
  • Parameter name mismatch, e.g., the macro needs BED / HOTEND, but the slicer passes BED_TEMP / EXTRUDER_TEMP.
  • The macro references a non-existent object, e.g., [heater_bed] is not in the configuration, but the macro reads printer.heater_bed.
  • The macro uses Jinja2 syntax with errors in parentheses, quotes, filters, or default values.
  • A command executed within the macro fails first, and the outer scope only shows it as Error evaluating.

Solution:

  1. Check the full Traceback below Error evaluating in klippy.log to identify which variable or command caused the error.
  2. Compare with the slicer's start G-code to confirm that the parameter names passed match params.xxx in the macro exactly, including case.
  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 module exists in the configuration.
  5. If the macro comes from a third-party configuration package, confirm that all dependent include files and base macros are loaded.

Related configuration reference: Macro Introduction.

SAVE_CONFIG Failure or Configuration Conflict​

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

Common Causes:

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

Solution:

  1. Confirm the 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 cannot start after SAVE_CONFIG, open printer.cfg and check the #*# auto-save area at the bottom.

  3. If the same option exists in an include file, delete the duplicate entry in the auto-save area, or change to 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 is still not possible, check disk space: df -h ~/printer_data/.

Related configuration reference: Configuration Modification Instructions.

SDCARD_RESET_FILE cannot be run from the sdcard​

Error Message: SDCARD_RESET_FILE cannot be run from the sdcard.

Common Causes:

  • The SDCARD_RESET_FILE command was executed during an SD card print. This command cannot be called during an SD card print.
  • The slicer's start G-code or a macro incorrectly includes SDCARD_RESET_FILE.

Solution:

  1. Check the slicer's start G-code and custom macros, and delete or comment out the SDCARD_RESET_FILE call.
  2. If resetting the SD card file status is truly necessary, execute it manually after the print is finished, not during the print process.
  3. If using a PRINT_START macro, confirm it does not call this command.
Loading...