Configuration Modification Notes
This page summarizes the most common formatting issues when modifying Klipper configurations. After modifying the configuration, save and restart Klipper, and locate problems based on error messages.
General configuration items should not be indented arbitrarily. Only the G-code content after gcode: within [gcode_macro XXXX] needs to be indented according to macro syntax.
Space and Indentation Errors
- Cause: Residual spaces or indentation before configuration items prevent Klipper from correctly identifying parameters.
- Solution: Remove extra spaces so that parameters start from the beginning of the line.
Comparison Examples
Incorrect Example:
Correct Example:
Configuration Comment Errors
Retaining Unnecessary Configurations
- Cause: The configuration file retains configuration sections that should not exist or are duplicated.
- Solution: Delete erroneous configurations, keeping only the configuration sections actually required by the current hardware.
Incomplete Section Commenting
Simply commenting out the [probe] section header is insufficient. All parameters within that configuration section must be commented out or deleted together until the next [xxxx] configuration section.
In the example below, the next configuration section is [homing_override].
Incorrect Example:
Correct Example:
Quick Reference for Common Configuration Errors
| Error Keyword | Common Cause | Solution |
|---|---|---|
Option 'xxx' is not valid | Misspelled configuration parameter name | Check if the parameter name matches the official documentation |
Section 'xxx' is not a valid config section | Incorrect configuration section name or missing plugin | Check section spelling, Klipper version, and plugin installation status |
Unable to open config file | The file referenced by include does not exist | Check if the file path is correct |
Unable to parse option | Parameter format does not meet requirements | Check numbers, coordinates, commas, and Chinese punctuation |
Pin 'xxx' is not a valid pin | Incorrect pin name format | Confirm the correct pin name based on the mainboard documentation |
pin xxx used multiple times | Same pin repeatedly occupied by multiple features | Search all include files and delete duplicate occurrences |
Duplicate chip name | Duplicate configuration sections with the same name | Delete duplicate [xxxx] configuration sections |
Unknown temperature sensor | Misspelled temperature sensor type | Confirm that the sensor_type name is correct |
For more configuration startup-related errors, refer to: Configuration Errors.