설정 클래스 오류

이 페이지에서는 설정 구간 충돌, 매개변수 오타, include 파일 및 SAVE_CONFIG 관련 문제를 정리합니다. 설정을 수정한 후에는 먼저 klippy.log의 첫 번째 설정 오류를 확인한 후, 항목별로 처리하세요.

homing override method always homes X and Y before homing Z

오류 메시지: 안전 Z 홈과 홈 오버라이드 설정이 충돌합니다.

Loading...

오류 원인: [safe_z_home]와 [homing_override]를 동시에 설정하여 Klipper가 어떤 홈 로직을 사용할지 확인할 수 없습니다.

해결 방법:

1. 설정 파일에서 [safe_z_home]와 [homing_override]를 검색합니다.
2. 기기의 실제 홈 로직에 따라 항목 하나만 남깁니다.
3. 저장 후 Klipper를 재시작합니다.

관련 설정 참고: 홈 및 방향 보정 가이드, 홈 오버라이드 참조 설정.

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

오류 메시지: Option 'xxx' is not valid in section 'yyy', 지정된 설정 구간에 인식되지 않는 옵션 이름이 있습니다.

일반적인 원인:

• 옵션 이름 오타, 예를 들어 sensor_pin을 sensor_ping으로 잘못 입력한 경우.
• 다른 설정 구간의 옵션을 현재 구간에 잘못 붙여넣은 경우, 예를 들어 [probe]의 옵션을 [stepper_z]에 작성한 경우.
• Klipper 버전 업그레이드 후 이전 버전에서 지원되던 옵션이 제거되거나 이름이 변경된 경우.
• 실제 매개변수가 아닌 주석 내용을 사용한 경우, 예를 들어 default_parameter_z.

해결 방법:

1. 오류에서 지적된 설정 구간과 옵션 이름을 주의 깊게 확인하여 철자를 확인합니다.
2. Klipper 설정 참조 문서를 참조하여 옵션이 어떤 설정 구간에 속하는지 확인합니다.
3. 최근 Klipper를 업그레이드했다면 설정 변경 기록을 확인하여 옵션에 변경 사항이 있는지 확인합니다.
4. 잘못된 옵션을 삭제하거나 올바른 설정 구간으로 이동합니다.

관련 설정 참고: 설정 수정 설명.

Section 'xxx' is not a valid config section

오류 메시지: Section 'xxx' is not a valid config section, Unknown config object 또는 특정 설정 구간을 Klipper가 인식할 수 없습니다.

일반적인 원인:

• 설정 구간 이름 오타, 예를 들어 [bed_mesh]를 [bedmesh]로 잘못 입력한 경우.
• 현재 Klipper 버전이 해당 설정 구간을 지원하지 않거나, 업데이트/다운그레이드 후 설정 형식이 호환되지 않는 경우.
• 타사 플러그인 설정을 복사했지만 해당 플러그인, 확장 모듈 또는 Klipper 브랜치가 설치되지 않은 경우.
• include 파일에 다른 기기나 다른 메인보드의 설정 구간이 포함된 경우.

해결 방법:

1. 오류의 설정 구간 이름을 기준으로 printer.cfg와 모든 include 파일에서 해당 구간을 찾습니다.
2. 철자가 Klipper 설정 참조와 일치하는지 확인하고, 설정 구간 이름에는 한자 괄호나 전각 기호를 사용하지 마십시오.
3. 설정이 타사 플러그인이나 사용자 정의 매크로 패키지에서 온 경우, 해당 플러그인이 설치되어 있고 현재 Klipper 버전과 호환되는지 확인합니다.
4. 해당 구간의 용도를 모르겠다면 먼저 설정 구간을 주석 처리하고 재시작하여 테스트한 후, 항목별로 복원합니다.

관련 설정 참고: 설정 수정 설명.

Unable to open config file / Include file does not exist

오류 메시지: Unable to open config file /home/xxx/printer_data/config/printer.cfg 또는 Include file 'xxx.cfg' does not exist.

일반적인 원인:

• printer.cfg 파일 경로가 잘못되었거나 파일이 실수로 삭제된 경우.
• [include]가 참조하는 하위 설정 파일이 존재하지 않거나 파일 이름이 일치하지 않는 경우.
• KIAUH 등의 설치 도구가 자동으로 [include] 참조를 생성했지만 해당 cfg 파일이 설치되지 않은 경우.
• 권한 문제로 Klipper가 설정 파일을 읽을 수 없는 경우.

해결 방법:

1. printer.cfg가 Klipper 설정 디렉토리(일반적으로 ~/printer_data/config/printer.cfg)에 존재하는지 확인합니다.
2. 모든 [include xxx.cfg] 줄을 확인하여 참조된 파일이 실제로 존재하는지 확인합니다.
3. fluidd.cfg 또는 mainsail.cfg가 누락된 경우 해당 웹 인터페이스의 설치 문서를 참조하여 설정을 추가합니다.
4. 설정 파일 권한이 올바른지 확인합니다: ls -la ~/printer_data/config/.

Fluidd / Mainsail 기본 설정 누락

오류 메시지: Fluidd 또는 Mainsail이 기본 설정 누락을 알립니다. 일반적인 키워드는 다음과 같습니다:

[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 알림 예시:

Loading...

Mainsail 알림 예시:

Loading...

일반적인 원인:

• printer.cfg에 [include fluidd.cfg] 또는 [include mainsail.cfg]가 활성화되지 않았습니다.
• 설정 디렉토리에 fluidd.cfg / mainsail.cfg가 없거나 include 파일 이름이 잘못되었습니다.
• 수동 설정 시 [virtual_sdcard], [pause_resume], [display_status]를 누락했습니다.
• CANCEL_PRINT 매크로가 정의되지 않았거나 매크로 파일이 include되지 않았습니다.

해결 방법:

1. 기본 프론트엔드 설정 파일을 우선적으로 사용해야 합니다. 일반 사용자가 알림을 무시하기 위해 몇 가지 설정 구간만 수동으로 추가하는 것은 권장되지 않습니다. 기본 fluidd.cfg / mainsail.cfg는 가상 SD 카드, 일시 중지/재개, 디스플레이 상태 및 인쇄 취소 매크로 등 프론트엔드에 필요한 기본 설정을 함께 제공합니다.

2. printer.cfg 상단에 현재 사용 중인 프론트엔드에 해당하는 include가 포함되어 있는지 확인합니다.

   [include fluidd.cfg]

   또는:

   [include mainsail.cfg]

3. FLY 사전 설정 시스템 또는 공식 참조 설정을 사용하는 경우 fluidd.cfg / mainsail.cfg 파일이 ~/printer_data/config/ 디렉토리에 있는지 확인합니다.

4. 해당 파일이 없으면 프론트엔드 기본 설정 파일을 다시 추가하거나 Fluidd 초기 설정 설명을 참조하세요.

5. 기본 프론트엔드 설정 파일을 활성화한 후 일시 중지, 재개, 인쇄 취소 위치 및 리트랙트 매개변수를 수정해야 하는 경우 일시 중지 및 인쇄 취소 사용자 정의 위치에 따라 _CLIENT_VARIABLE을 추가하고 기본 CANCEL_PRINT / PAUSE / RESUME 매크로를 직접 복사하거나 덮어쓰지 마십시오.

6. 사용자 지정 시스템을 유지 관리하고 프론트엔드 매크로 종속성을 명확히 알고 있는 경우에만 기본 구간을 수동으로 추가하는 것을 고려하십시오. 이 방법은 일반 사용자에게 권장되지 않으며, 최소한 다음이 포함되어야 합니다:

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

   또한 사용 가능한 [gcode_macro CANCEL_PRINT]를 제공해야 합니다. 그렇지 않으면 프론트엔드에서 여전히 CANCEL_PRINT macro not found in configuration을 알릴 수 있습니다.

7. 설정을 저장한 후 RESTART를 실행합니다. 여전히 누락되었다고 알리면 모든 include 파일이 실제로 Klipper에 의해 읽혀지는지 계속 확인합니다.

프론트엔드 매크로 사용 방법: 일시 중지 및 인쇄 취소 사용자 정의 위치 매크로 설정 참고: 매크로 소개

Unable to parse option / option must be specified

오류 메시지: Unable to parse option 'xxx' in section 'yyy', Option 'xxx' in section 'yyy' must be specified, 또는 must have minimum/maximum, must be above/below.

일반적인 원인:

• 필수 매개변수 누락, 예를 들어 [extruder]에 step_pin, dir_pin, heater_pin 또는 sensor_type이 없는 경우.
• 매개변수 형식 오류, 예를 들어 숫자가 필요한 곳에 텍스트가 입력되었거나 좌표 목록에 쉼표가 누락된 경우.
• 매개변수 값이 Klipper 허용 범위를 벗어난 경우, 예를 들어 run_current, max_temp, position_max 설정이 부적절한 경우.
• 설정을 복사할 때 한자 구두점, 전각 기호 또는 보이지 않는 문자가 유지된 경우.

해결 방법:

1. 오류의 설정 구간과 매개변수 이름을 기준으로 해당 .cfg 파일에서 항목별로 확인합니다.
2. 숫자, 좌표 및 목록 매개변수의 경우 형식이 예제와 일치하는지 확인합니다. 예를 들어 mesh_min: 20, 20.
3. must be above/below 또는 minimum/maximum의 경우 먼저 공식 예제나 메인보드 튜토리얼에서 권장하는 값으로 복원합니다.
4. 저장한 후 RESTART를 실행하고, 여전히 실패하면 klippy.log의 첫 번째 설정 오류를 확인합니다.

관련 설정 참고: 설정 수정 설명.

Unknown pin chip name / Pin is not a valid pin name / pin used multiple times

오류 메시지: 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.

일반적인 원인:

• 다중 MCU 설정에서 핀 접두사를 잘못 작성한 경우, 예를 들어 toolboard:PB0를 작성해야 하는데 존재하지 않는 MCU 이름을 작성한 경우.
• MCU ID(canbus_uuid 또는 serial) 설정이 잘못되어 핀 매핑이 다른 장치로 잘못 연결되어 해당 장치에 해당 핀이 없는 경우.
• 핀 이름 철자 오류 또는 메인보드 튜토리얼의 핀을 다른 메인보드에 직접 복사한 경우.
• 동일한 물리적 핀이 여러 기능에 의해 중복 점유된 경우, 예를 들어 팬, 히터, 엔드스톱이 동시에 동일한 핀을 사용하는 경우.
• 핀 반전 !, 풀업 ^, 풀다운 ~가 잘못된 위치에 작성된 경우.

해결 방법:

1. [mcu xxx]의 이름이 핀 접두사와 완전히 일치하는지 확인합니다. 대소문자도 일치해야 합니다.
2. [mcu xxx] 구간의 canbus_uuid 또는 serial이 실제 장치와 일치하는지 확인합니다(ls /dev/serial/by-id/ 또는 python3 -c "import can; ..." 사용 가능).
3. 메인보드 핀 맵을 대조하여 각 pin:, step_pin:, dir_pin:, heater_pin:이 현재 메인보드에 속하는지 확인합니다.
4. 모든 include 파일에서 오류 핀을 검색하여 중복 점유 항목을 삭제하거나 변경합니다.
5. 핀 수정자는 핀 이름 앞에 작성해야 합니다. 예를 들어 ^PB7, !PC13, mcu2:^PB7.

관련 설정 참고: 설정 수정 설명, 팬 참조 설정.

gcode command XXX already registered

오류 메시지: Error: gcode command XXX already registered.

오류 원인: 두 개의 다른 매크로 또는 시스템 모듈이 동일한 G-code 명령 이름을 등록했습니다. 예를 들어 두 매크로 모두 [gcode_macro NEXT]를 정의한 경우.

일반적인 시나리오:

• 사용자 정의 매크로가 Klipper 시스템 모듈 또는 타사 설정과 충돌합니다.
• 여러 [gcode_macro M600] 정의.

해결 방법:

1. printer.cfg 및 모든 [include] 파일에서 중복 정의를 검색합니다.
2. 충돌하는 [gcode_macro]를 삭제하거나 이름을 변경합니다.
3. [homing_override], [gcode_macro PAUSE], [gcode_macro RESUME], [gcode_macro CANCEL_PRINT] 등 일반적인 매크로를 확인합니다.

관련 설정 참고: 매크로 소개.

Unknown command:"XXX"

오류 메시지: 콘솔 또는 klippy.log에 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" 등이 나타납니다.

일반적인 원인:

• 슬라이서 시작 또는 종료 G-code가 Klipper에 존재하지 않는 매크로를 호출합니다. 예를 들어 슬라이서가 PRINT_START를 보내지만 설정에 [gcode_macro START_PRINT]만 정의된 경우.
• Marlin에서 마이그레이션된 명령을 사용했으며 Klipper가 기본적으로 지원하지 않거나 매크로로 호환해야 하는 경우.
• 객체 제외 기능이 활성화되었지만 슬라이서, Moonraker 또는 Klipper 설정이 완전하지 않아 EXCLUDE_OBJECT_DEFINE, EXCLUDE_OBJECT_START, EXCLUDE_OBJECT_END 등의 명령을 인식할 수 없는 경우.
• 팬이 [fan_generic] 또는 [output_pin]을 사용하지만 슬라이서가 여전히 기본 M106 / M107을 보내는 경우.
• 타사 매크로 패키지 사용 시 include 파일이 누락되었거나 매크로 이름이 슬라이서에 입력된 이름과 일치하지 않는 경우.

해결 방법:

1. printer.cfg 및 모든 include 파일에서 오류의 명령 이름을 검색하여 해당 [gcode_macro XXX]가 있는지 확인합니다.
2. 슬라이서의 시작, 종료, 필라멘트 교체, 팬 및 객체 제외 명령 이름을 Klipper 매크로와 일치시킵니다.
3. Marlin 명령의 경우 불필요한 명령을 우선 삭제하고, 호환이 정말 필요한 경우에만 명확한 Klipper 매크로를 추가합니다.
4. 객체 제외 관련 오류는 슬라이서가 객체 태그를 출력하는지, Moonraker가 객체 처리를 활성화했는지, Klipper에 [exclude_object]가 있는지 동시에 확인해야 합니다.
5. 팬 명령 오류 시 [fan]을 사용해야 하는지, 아니면 [fan_generic] / [output_pin]에 일치하는 제어 매크로를 추가해야 하는지 확인합니다.

EXCLUDE_OBJECT_DEFINE / START / END

오류 의미: EXCLUDE_OBJECT_DEFINE은 인쇄 객체를 정의하는 데 사용되고, EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END는 현재 G-code가 어떤 객체에 속하는지 표시하는 데 사용됩니다. 그래야 프론트엔드가 다중 객체 인쇄 시 특정 객체를 표시하고 제외할 수 있습니다. klippy.log에 Unknown command:"EXCLUDE_OBJECT_DEFINE", Unknown command:"EXCLUDE_OBJECT_START" 또는 Unknown command:"EXCLUDE_OBJECT_END"가 반복해서 나타나면 G-code에 이미 객체 제외 명령이 포함되어 있지만 Klipper의 현재 설정이 이러한 명령을 올바르게 수신하지 못하고 있음을 의미합니다.

우선 확인 사항:

1. printer.cfg 또는 include된 설정 파일에 다음이 있는지 확인합니다:

[exclude_object]

2. 수정 후 RESTART를 실행한 다음 G-code 파일을 다시 업로드하여 테스트합니다. 이미 업로드된 이전 파일은 최신 설정으로 처리되지 않았을 수 있으므로 다시 슬라이싱하거나 다시 업로드하는 것이 좋습니다.
3. Moonraker 설정에서 객체 처리가 활성화되었는지 확인합니다. 일반적인 설정 위치는 moonraker.conf입니다:

[file_manager]
enable_object_processing: True

4. 슬라이서에서 객체 태그 / 객체 제외 관련 출력이 활성화되었는지 확인합니다. 슬라이서마다 이름이 다르며, 일반적인 현상은 G-code에서 EXCLUDE_OBJECT_DEFINE, EXCLUDE_OBJECT_START, EXCLUDE_OBJECT_END 또는 객체 이름을 검색할 수 있는 것입니다.
5. 일시적으로 인쇄를 완료하고 객체 제외 기능이 필요하지 않은 경우 슬라이서에서 객체 제외 관련 출력을 비활성화한 후 다시 슬라이싱합니다. 파일의 일부 객체 명령만 삭제하지 마십시오. 그렇지 않으면 프론트엔드 객체 목록이 비정상적일 수 있습니다.

판단 방향:

• EXCLUDE_OBJECT_START / EXCLUDE_OBJECT_END만 오류: 우선 [exclude_object]를 추가한 다음 Klipper를 재시작합니다.
• 프론트엔드에 객체 목록이 없지만 Klipper가 더 이상 Unknown command를 알리지 않음: 우선 Moonraker의 객체 처리 및 G-code가 다시 업로드되었는지 확인합니다.
• 파일에서 객체 관련 명령을 전혀 검색할 수 없음: 슬라이서가 객체 태그를 출력하지 않았음을 의미하므로 슬라이서 측에서 활성화해야 합니다.

관련 설정 참고: 매크로 소개, 설정 수정 설명.

Error evaluating 'gcode_macro XXX:gcode'

오류 메시지: 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.

일반적인 원인:

• 슬라이서가 매크로에 필요한 매개변수를 전달하지 않았습니다. 예를 들어 매크로에서 params.HOTEND를 읽지만 슬라이서가 HOTEND=를 전달하지 않은 경우.
• 매개변수 이름이 일치하지 않습니다. 예를 들어 매크로는 BED / HOTEND가 필요하지만 슬라이서가 실제로 BED_TEMP / EXTRUDER_TEMP를 전달한 경우.
• 매크로가 존재하지 않는 객체를 참조합니다. 예를 들어 설정에 [heater_bed]가 없지만 매크로가 printer.heater_bed를 읽는 경우.
• 매크로에서 Jinja2 구문을 사용했지만 괄호, 따옴표, 필터 또는 기본값 작성이 잘못된 경우.
• 매크로 내에서 실행된 명령이 먼저 오류를 발생시키고 외부에서는 Error evaluating으로만 표시되는 경우.

해결 방법:

1. klippy.log에서 Error evaluating 아래의 전체 Traceback을 확인하여 어떤 변수 또는 명령이 오류인지 확인합니다.
2. 슬라이서 시작 G-code와 대조하여 전달된 매개변수 이름이 매크로의 params.xxx와 완전히 일치하는지 확인합니다. 대소문자도 일치해야 합니다.
3. 선택적 매개변수에 기본값을 설정합니다. 예를 들어 params.BED|default(60)|float를 사용하여 매개변수가 비어 있을 때 오류가 발생하지 않도록 합니다.
4. 매크로에서 사용된 printer.xxx 객체를 검색하여 설정에 해당 모듈이 있는지 확인합니다.
5. 매크로가 타사 설정 패키지에서 온 경우 모든 종속 include 파일과 기본 매크로가 로드되었는지 확인합니다.

관련 설정 참고: 매크로 소개.

SAVE_CONFIG 실패 또는 설정 충돌

오류 메시지: SAVE_CONFIG 실행 후 Unable to write config, Option conflict, Cannot save config가 표시되거나 저장 후 프린터를 시작할 수 없습니다.

일반적인 원인:

• printer.cfg 파일 권한이 부족하여 Klipper 프로세스가 쓸 수 없습니다. sudo를 사용하여 설정 파일을 편집한 후 자주 발생합니다.
• 자동 저장 영역(#*# 표시 블록)의 설정 항목이 수동 [include] 파일의 동일한 옵션과 충돌합니다.
• MCU가 shutdown 상태여서 SAVE_CONFIG가 새 설정을 정상적으로 전달할 수 없습니다.
• printer.cfg 파일 끝에 구문 오류가 있거나 잘려서 자동 저장 영역 쓰기가 실패했습니다.
• 여러 include 파일이 SAVE_CONFIG가 자동 저장해서는 안 되는 PID, Z offset 등의 매개변수를 중복 정의했습니다.

해결 방법:

1. 설정 파일 권한 확인:

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

   소유자가 현재 사용자가 아닌 경우 sudo chown $USER:$USER ~/printer_data/config/printer.cfg를 실행합니다.

2. SAVE_CONFIG 후 프린터를 시작할 수 없으면 printer.cfg 하단을 열어 #*# 자동 저장 영역을 확인합니다.

3. 동일한 옵션이 include 파일에도 존재하는 경우 자동 저장 영역의 중복 항목을 삭제하거나 include 파일에서 통합 관리하도록 변경합니다.

4. MCU가 shutdown 상태이면 먼저 FIRMWARE_RESTART를 실행한 다음 SAVE_CONFIG를 다시 실행합니다.

5. 권한은 정상이지만 여전히 쓸 수 없는 경우 디스크 공간을 확인합니다: df -h ~/printer_data/.

관련 설정 참고: 설정 수정 설명.

SDCARD_RESET_FILE cannot be run from the sdcard

오류 메시지: SDCARD_RESET_FILE cannot be run from the sdcard.

일반적인 원인:

• SD 카드 인쇄 중에 SDCARD_RESET_FILE 명령이 실행되었습니다. 이 명령은 SD 카드 인쇄 중에는 호출할 수 없습니다.
• 슬라이서 시작 G-code 또는 매크로에 SDCARD_RESET_FILE이 잘못 포함되었습니다.

해결 방법:

1. 슬라이서 시작 G-code 및 사용자 정의 매크로를 확인하여 SDCARD_RESET_FILE 호출을 삭제하거나 주석 처리합니다.
2. SD 카드 파일 상태를 재설정해야 하는 경우 인쇄가 끝난 후 수동으로 실행하고 인쇄 흐름에 포함시키지 마십시오.
3. PRINT_START 매크로를 사용하는 경우 이 명령이 호출되지 않았는지 확인합니다.