Skip to main content

Configuration Errors

This page focuses on configuration section conflicts, parameter spelling, include files, and SAVE_CONFIG related issues. After modifying configuration, please first check the first configuration error in klippy.log, then address each issue 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 simultaneously, 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 references: 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 names, such as writing sensor_pin as sensor_ping.
  • Accidentally pasting options from other configuration sections into the current one, such as writing [probe] options into [stepper_z].
  • After a Klipper upgrade, options supported by older versions have been removed or renamed.
  • Using commented content that is not an actual parameter, such as 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 should belong to.
  3. If Klipper was recently upgraded, check the Configuration Changes Log to see if the option has changed.
  4. Delete invalid options or move them to the correct configuration section.

Related configuration references: 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 configuration section cannot be recognized by Klipper.

Common Causes:

  • Misspelled configuration section names, such as writing [bed_mesh] as [bedmesh].
  • The current Klipper version does not support this configuration section, or the configuration format is incompatible after an update/downgrade.
  • Copied third-party plugin configurations, but the corresponding plugin, extension module, or Klipper branch is not installed.
  • Include files retain configuration sections from other machines or other motherboards.

Solution:

  1. Based on the configuration section name in the error, locate the corresponding section 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 in 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 section, comment it out and restart to test first, then restore items one by one.

Related configuration references: 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 was accidentally deleted.
  • The sub-configuration file referenced by [include] does not exist or the filename does not match.
  • Tools like KIAUH automatically generate [include] references, but the corresponding cfg file was not installed.
  • Permission issues prevent Klipper from reading the configuration file.

Solution:

  1. Confirm whether 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 fluidd.cfg or mainsail.cfg is missing, add the configuration by referring to the corresponding Web interface installation documentation.
  4. Ensure the configuration file permissions are correct: ls -la ~/printer_data/config/.

Fluidd / Mainsail Basic Configuration Missing​

Error Message: Fluidd or Mainsail reports missing basic configuration. 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 example:

Loading...

Mainsail example:

Loading...

Common Causes:

  • printer.cfg does not enable [include fluidd.cfg] or [include mainsail.cfg].
  • fluidd.cfg / mainsail.cfg is missing from the configuration directory, or the include filename is misspelled.
  • When manually configuring, [virtual_sdcard], [pause_resume], [display_status] were omitted.
  • CANCEL_PRINT macro is not defined, or the macro file is not included.

Solution:

  1. It is mandatory to prioritize using the default frontend configuration file. It is not recommended for regular users to bypass the warning by manually adding a few configuration sections. The default fluidd.cfg / mainsail.cfg provides the basic configuration needed by the frontend, including virtual SD card, pause/resume, display status, and cancel print macros.

  2. Confirm whether printer.cfg contains the include corresponding to the current frontend at the top:

    [include fluidd.cfg]

    Or:

    [include mainsail.cfg]

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

  4. If the corresponding file does not exist, re-add the frontend default configuration file, or refer to the Fluidd Initial Configuration Guide.

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

  6. Only when maintaining a custom system and clearly understanding the frontend macro dependencies, consider manually supplementing the basic sections. This approach is not recommended for regular users and at minimum needs to include:

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

    [pause_resume]

    [display_status]

    Additionally, a working [gcode_macro CANCEL_PRINT] must be provided, otherwise the frontend will still report CANCEL_PRINT macro not found in configuration.

  7. After saving the configuration, execute RESTART. If the warning persists, continue checking whether all include files are actually being read by Klipper.

Frontend Macro Usage Guide: Pause and Cancel Print Custom 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 parameters are missing, for example, [extruder] is missing step_pin, dir_pin, heater_pin, or sensor_type.
  • Parameter format errors, such as providing text where a number is required, or missing a comma in a coordinate list.
  • Parameter values exceed the range allowed by Klipper, for example, unreasonable settings for run_current, max_temp, or position_max.
  • When copying configuration, Chinese punctuation, full-width symbols, or invisible characters were retained.

Solutions:

  1. Based on the configuration section and parameter name in the error message, go back to the corresponding .cfg file and check each item.
  2. For numbers, coordinates, and list parameters, confirm the format matches the examples, for example, mesh_min: 20, 20.
  3. For must be above/below or minimum/maximum errors, first restore the values to the official examples or the recommended values from 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 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:

  • In a multi-MCU setup, the pin prefix is written incorrectly, for example, toolboard:PB0 was intended, but a non-existent MCU name was used.
  • The MCU ID (canbus_uuid or serial) is configured incorrectly, causing the pin to be mapped to the wrong device which does not have the corresponding pin.
  • Pin names are misspelled, or a pin from one motherboard's tutorial was directly copied to another motherboard.
  • The same physical pin is used by multiple features simultaneously, such as a fan, heater, and endstop all using the same pin.
  • The pin modifiers ! (inverted), ^ (pull-up), or ~ (pull-down) are placed in the wrong position.

Solutions:

  1. Verify that the name in [mcu xxx] exactly matches the pin prefix, including case sensitivity.
  2. Verify that the canbus_uuid or serial in the [mcu xxx] section matches the actual device (can be checked with ls /dev/serial/by-id/ or python3 -c "import can; ...").
  3. Cross-reference the motherboard pinout diagram to ensure that every pin:, step_pin:, dir_pin:, and heater_pin: belongs to the current motherboard.
  4. Search all include files for the erroring pin, and delete or change duplicate usages.
  5. Pin modifiers should be written before the pin name, for example, ^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.

Error cause: Two different macros or system modules register the same G-code command name, for example, two macros both define [gcode_macro NEXT].

Common scenarios:

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

Solutions:

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

Related configuration reference: Macros Introduction.

Unknown command:"XXX"​

Error message: The console or klippy.log shows 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", etc.

Common causes:

  • The slicer's start or end G-code calls a macro that does not exist in Klipper, for example, the slicer sends PRINT_START, but only [gcode_macro START_PRINT] is defined in the configuration.
  • Commands migrated from Marlin are used, which Klipper does not support by default or requires a macro for compatibility.
  • The exclude object feature is enabled, but the slicer, Moonraker, or Klipper configuration is incomplete, so commands like EXCLUDE_OBJECT_DEFINE, EXCLUDE_OBJECT_START, and EXCLUDE_OBJECT_END are not recognized.
  • The fan uses [fan_generic] or [output_pin], but the slicer still sends the default M106 / M107.
  • Using a third-party macro package, an include file is missing, or the macro name does not match the name filled in the slicer.

Solutions:

  1. Search for the command name from the error in printer.cfg and all include files to see if the corresponding [gcode_macro XXX] exists.
  2. Make sure the names of the start, end, filament change, fan, and exclude object commands in the slicer match the Klipper macro names.
  3. If it's a Marlin command, first prefer deleting the unneeded commands; if compatibility is strictly required, then add a clear Klipper macro.
  4. For exclude object errors, simultaneously check whether the slicer outputs object labels, whether Moonraker has object processing enabled, and whether 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].

EXCLUDE_OBJECT_DEFINE / START / END​

Error meaning: EXCLUDE_OBJECT_DEFINE is used to define a print object, and EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END are 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 receiving this type of command.

Priority checks:

  1. Confirm that [exclude_object] exists in printer.cfg or an included configuration file:
[exclude_object]
  1. After modification, execute RESTART and then re-upload the G-code file to test. Old files that were uploaded previously may not have been processed with the latest configuration. It's recommended to re-slice or re-upload.
  2. Check if Moonraker configuration has object processing enabled. A common configuration location is in moonraker.conf:
[file_manager]
enable_object_processing: True
  1. Check if the slicer has object labeling / exclude object output enabled. The terminology varies between slicers, but a common indicator is finding EXCLUDE_OBJECT_DEFINE, EXCLUDE_OBJECT_START, EXCLUDE_OBJECT_END, or object names when searching the G-code.
  2. If you just want to complete the print temporarily and don't need object exclusion, disable the object exclusion output in the slicer and re-slice; don't just delete part of the object commands from the file, as this may cause the frontend object list to behave abnormally.

Diagnostic direction:

  • Only EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END are reported: prioritize adding [exclude_object], then restart Klipper.
  • The 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.
  • No object-related commands can be found in the file at all: this means the slicer didn't output object labels, and you need to enable it on the slicer side.

Related configuration reference: Macros 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 the required parameters to the macro. For example, the macro reads params.HOTEND, but the slicer did not pass HOTEND=.
  • Parameter names are inconsistent. For example, the macro requires BED / HOTEND, but the slicer actually passes BED_TEMP / EXTRUDER_TEMP.
  • The macro references a non-existent object. For example, [heater_bed] is not present in the configuration, but the macro reads printer.heater_bed.
  • The macro uses Jinja2 syntax, but parentheses, quotes, filters, or default value syntax are incorrect.
  • A command executed within the macro fails first, and the outer layer only displays Error evaluating.

Solutions:

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

Related configuration reference: Macro Introduction.

SAVE_CONFIG failure or configuration conflict​

Error message: After executing SAVE_CONFIG, the system prompts Unable to write config, Option conflict, Cannot save config, or after a restart, Can't read autosave from config file - modifications after header appears.

Common Causes:

  • The printer.cfg file lacks sufficient permissions for the Klipper process to write to it. This commonly occurs after editing the configuration file with sudo.
  • Configuration items in the autosave section (the #*# marker block) conflict with the same options in manually managed [include] files.
  • The MCU is in a shutdown state, and SAVE_CONFIG cannot properly apply the new configuration.
  • There is a syntax error or truncation at the end of the printer.cfg file, causing the autosave section write to fail.
  • Normal configuration, comments, or other non-#*# lines were manually added after the #*# <---------------------- SAVE_CONFIG ----------------------> marker. Klipper therefore refuses to read the autosave section.
  • The header of the autosave section or the #*# lines were corrupted during manual editing, configuration merging, or file synchronization.
  • Multiple include files redundantly define parameters that should not be automatically saved by SAVE_CONFIG, such as PID or Z offset.

Solutions:

  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 the bottom of printer.cfg and check the #*# autosave section.

  3. If modifications after header appears, back up printer.cfg first, then search for the autosave marker:

    grep -nE 'SAVE_CONFIG|DO NOT EDIT|^#\*#' ~/printer_data/config/printer.cfg

  4. Move all configuration that needs manual maintenance to before the SAVE_CONFIG header. After the header, only Klipper-generated #*# lines should remain; do not delete the entire autosave section directly, as saved calibration values such as PID, Z offset, and mesh bed may be lost.

  5. If the autosave section is already corrupted or multiple headers exist, prioritize restoring from the latest and confirmed usable printer-*.cfg backup in the same directory, then re-perform necessary calibrations. Do not simply concatenate multiple autosave sections together.

  6. If the same option also exists in an include file, delete the duplicate item from the autosave section, or manage it uniformly in the include file instead.

  7. If the MCU is in a shutdown state, first address the earliest real error and execute FIRMWARE_RESTART, then re-execute SAVE_CONFIG.

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

Related configuration reference: Configuration Modification Notes.

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 is not allowed to be called during SD card printing.
  • The slicer's start G-code or a macro mistakenly includes SDCARD_RESET_FILE.

Solutions:

  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 state is truly necessary, execute it manually after the print finishes. Do not place it in the print process.
  3. If using a PRINT_START macro, confirm that this command is not called within it.
Loading...