자주 발생하는 오류 총정리

이 페이지는 Klipper의 일반적인 오류를 빠르게 파악하기 위한 것입니다. 먼저 klippy.log에서 전체 오류 키워드를 찾은 후, 해당 분류 페이지로 이동하여 문제를 처리하세요.

빠른 색인

오류 유형	일반적인 키워드	문제 확인 시작점
연결 문제	Unable to connect、Invalid CAN uuid、Lost communication、MCU Protocol error、/dev/serial/by-id	본 페이지 연결 문제, MCU ID 설정, CAN 네트워크 및 ID 검색
설정 문제	not valid、not a valid config section、must be specified、Unable to parse、SAVE_CONFIG、Option conflict	설정 관련 오류
매크로 및 슬라이서 명령	Unknown command、Error evaluating 'gcode_macro、jinja2.exceptions.UndefinedError、dict object has no attribute	설정 관련 오류
운동/귀환	Move out of range、Must home axis first、No trigger、Endstop still triggered	운동, 리미트 및 레벨링 오류
G-code 해석	Unable to parse move、Invalid speed、Machine does not support G20、G2/G3	운동, 리미트 및 레벨링 오류, 호 피팅 권장사항
프로브 레벨링	Probe triggered、No trigger on probe、samples_tolerance、bed_mesh、BLTouch failed、Z_TILT、QUAD_GANTRY_LEVEL	운동, 리미트 및 레벨링 오류
온도 가열	ADC out of range、not heating at expected rate、Verify heater、temperature	온도, 가열 및 압출 오류
압출 문제	Extrude below minimum temp、Extrude only move too long、Move exceeds maximum extrusion、Filament sensor、M600	온도, 가열 및 압출 오류
성능 타임아웃	Timer too close、Missed scheduling、Stepper too far in past、Rescheduled timer、restarting too fast、SD busy	시스템, 성능 및 서비스 오류
TMC 드라이버	Unable to read tmc uart、Unable to write tmc spi、GSTAT、coil short circuit	TMC 오류 진단
CAN 네트워크	bytes_invalid、Network is down、No buffer space available、Invalid CAN uuid	CAN 네트워크 및 ID 검색
센서 주변기기	Invalid adxl345 id、No data、Insufficient axis、Eddy current sensor error、Invalid read data	가속도계 테스트 및 보정, EDDY 문제 모음

관련 설정 페이지 빠른 확인

오류 방향	추천 참고
설정 문법, 들여쓰기, 주석, 핀 중복	설정 수정 설명
귀환 방향, 축 방향, 강제 이동	귀환 및 방향 보정 가이드
리미트, TAP, 광학 리미트, 근접 스위치	리미트 관련
리미트 없는 귀환, 가상 리미트 감도	리미트 없이 사용하기
가열, PID, 느린 가열, 온도 보호	가열 관련, verify_heater 최적화, M109 최적화
팬 설정, 드라이버 팬, 7040 팬	팬 참조 설정
압출기 파라미터, 회전 거리, 압출 설정	압출기 참조 설정, 기계 보정
시작/종료 매크로, 일시정지/재개, 레벨링 및 메쉬 매크로	매크로 소개
자주 사용하는 디버그 명령어, 프로브, 공진 보상	자주 사용하는 디버그 명령어

연결 문제

MCU ID 설정 설명

Klipper에서 MCU ID는 [mcu] 또는 [mcu xxx] 설정 구간에서 제어 보드 연결을 식별하는 정보를 의미합니다. 통신 방식에 따라 작성 방법이 다릅니다:

연결 방식	설정 항목	예시
USB 펌웨어	serial:	serial: /dev/serial/by-id/usb-Klipper_xxxxxxxxxxxx
CAN 펌웨어	canbus_uuid:	canbus_uuid: xxxxxxxxxxxx
상위 컴퓨터 MCU	serial:	serial: /tmp/klipper_host_mcu

작성 규칙:

1. 메인보드는 기본적으로 [mcu]를 사용하며, 툴보드나 확장 보드는 [mcu tool], [mcu toolboard] 등 사용자 정의 이름을 사용합니다.
2. USB 펌웨어는 serial:만 입력하고, CAN 펌웨어는 canbus_uuid:만 입력하며, 동일한 [mcu]에 두 항목을 동시에 유지하지 마십시오.
3. 다중 MCU 기기에서는 각 [mcu xxx]가 자신의 실제 ID를 사용해야 하며, 동일한 USB ID나 CAN UUID를 복사하지 마십시오.
4. [mcu xxx]의 이름은 핀 접두사에 영향을 미칩니다. 예를 들어 [mcu tool]의 핀은 tool:gpio13으로 작성해야 하며, 이름의 대소문자는 일관되게 유지해야 합니다.
5. 문서 예시의 xxxxxxxx는 직접 사용할 수 없으며, 실제 검색된 ID로 반드시 교체해야 합니다.

일반적인 오류:

• katapult, canboot 등이 포함된 굽기 모드 ID를 Klipper 펌웨어 ID로 잘못 사용하는 경우.
• USB 펌웨어에 canbus_uuid:를 설정하거나, CAN 펌웨어에 기존 serial:을 유지하는 경우.
• 툴보드를 [mcu]로 설정하여 메인보드 MCU 설정을 덮어쓰는 경우.
• 핀 접두사와 MCU 이름이 일치하지 않는 경우. 예를 들어 설정이 [mcu toolboard]인데 핀을 tool:gpio13으로 작성하는 경우.

USB ID 확인: USB 펌웨어는 ls /dev/serial/by-id/* 명령어를 실행하여 ID를 확인할 수 있습니다.

CAN ID 확인: CAN 네트워크 및 ID 검색

툴보드 설정: 툴보드 MCU 추가 및 보드 간 설정

mcu 'xxx': Unable to connect

오류 정보: 호스트 시스템이 메인보드를 찾거나 연결할 수 없습니다.

Loading...

일반적인 원인:

• USB 장치 ID가 입력되지 않았거나 잘못 입력되었습니다.
• CAN UUID가 입력되지 않았거나, 잘못 입력되었거나, 장치가 온라인 상태가 아닙니다.
• UTOC, USB 케이블, CAN 브릿지 펌웨어 또는 전원 공급에 이상이 있습니다.
• CAN0이 시작되지 않았거나 CAN 네트워크 설정에 이상이 있습니다.

처리 방법:

1. klippy.log를 열고 가장 아래로 스크롤하여 구체적인 오류 정보를 확인합니다.

2. [Errno 2]가 나타나면 일반적으로 검색된 USB 장치 ID가 printer.cfg에 추가되지 않았음을 의미합니다.

   Loading...

3. Serial connection closed가 나타나면 일반적으로 CAN ID를 다시 검색하고 CAN 네트워크를 확인해야 합니다.

   Loading...

4. Unable to open CAN port: [Errno 19] No such device가 나타나면 일반적으로 UTOC 장치, USB 브릿지 CAN 펌웨어 또는 CAN0 장치가 없음을 의미합니다.

   Loading...

5. [Errno 100] Network is down 또는 [Errno 105] No buffer space available가 나타나면 CAN 네트워크 및 ID 검색에 따라 CAN0 설정을 다시 확인하세요.

mcu 'mcu': Invalid CAN uuid

오류 정보: CAN UUID가 유효하지 않거나 인식할 수 없습니다.

Loading...

오류 원인: canbus_uuid:가 잘못 입력되었거나, 장치가 온라인 상태가 아니거나, CAN 네트워크가 정상적으로 통신하지 못하고 있습니다.

해결 방법:

1. CAN 네트워크 및 ID 검색에 따라 CAN UUID를 다시 검색합니다.
2. printer.cfg에 실제 검색된 UUID가 입력되었는지 확인합니다.
3. 동일한 [mcu]에 serial:과 canbus_uuid:가 동시에 활성화되지 않았는지 확인합니다.
4. CAN-H, CAN-L, 종단 저항, 전원 공급 및 펌웨어 CAN 속도를 확인합니다.

Option 'serial' in section 'mcu' must be specified

오류 정보: [mcu] 설정 섹션에 serial을 반드시 지정해야 합니다.

Loading...

오류 원인: USB 펌웨어 연결 시 serial:을 입력하지 않았거나 [mcu] 설정 섹션이 실수로 삭제되었습니다.

해결 방법:

1. USB 장치 ID를 다시 검색합니다.
2. printer.cfg의 [mcu] 설정 섹션에 다음을 입력합니다:

[mcu]
serial: /dev/serial/by-id/실제 검색된 ID

3. 저장하고 Klipper를 재시작합니다.

현재 메인보드에 CAN 펌웨어가 플래시된 경우 canbus_uuid:를 사용하고 serial:을 계속 입력하지 마세요.

USB ID를 찾을 수 없음 / 시스템 서비스 간섭

오류 정보: ls /dev/serial/by-id/* 실행 시 출력이 없거나 No such file or directory 오류가 발생합니다. Klipper 연결 시 mcu 'xxx': Unable to open serial port, [Errno 2] No such file or directory 오류가 발생하거나 USB 메인보드가 시스템에서 반복적으로 연결이 끊겼다가 다시 연결됩니다.

일반적인 원인:

• 메인보드가 Klipper 펌웨어 실행 상태가 아니라 Katapult / CanBoot / DFU 등의 플래시 모드에 있습니다.
• USB 케이블, USB 포트, 호스트 시스템 전원 또는 메인보드 전원 공급에 이상이 있습니다.
• Debian 11 Bullseye의 일부 udev 버전에 문제가 있어 /dev/serial/by-id/ 장치 경로가 생성되지 않을 수 있습니다.
• 데스크탑 Linux에 ModemManager 또는 BRLtty가 설치되어 있을 수 있으며, 이러한 서비스가 직렬 포트를 선점하여 Klipper가 메인보드에 안정적으로 연결되지 못할 수 있습니다.

진단 방법:

전원 차단 작업

USB 케이블을 다시 꽂거나, 메인보드 전원 케이블을 확인하거나, USB/CAN 케이블을 정리하기 전에 프린터를 완전히 끄고 전원 공급을 차단하십시오. 전원이 켜진 상태에서 인터페이스 케이블 순서를 정리하거나 터미널을 건드리지 마십시오.

1. 먼저 메인보드에 Klipper 펌웨어가 플래시되어 실행 중인지 확인하십시오. USB ID에는 usb-Klipper가 포함되어야 하며, printer.cfg에 katapult, canboot, Bootloader 또는 DFU 모드 ID를 입력하지 마십시오.
2. 전원을 차단한 후 안정적인 USB 데이터 케이블과 호스트 시스템 USB 인터페이스로 교체하고, 전원을 다시 켠 후 ls /dev/serial/by-id/*를 다시 실행합니다.
3. Debian 11 Bullseye, 구형 MainsailOS / FluiddPi / Armbian 등을 사용하는 경우 다음 명령을 실행하여 udev 버전을 확인합니다:

apt-cache policy udev

4. Debian 11의 udev 문제로 확인되면 시스템 정식 업데이트 소스를 통해 udev를 업그레이드하거나 최신 시스템 이미지로 교체하는 것이 좋습니다.
5. 직렬 포트를 선점할 수 있는 서비스가 있는지 확인합니다:

systemctl list-units --all | grep -Ei 'ModemManager|brltty'

6. 이러한 서비스가 설치되어 있고 현재 호스트 시스템에 모뎀이나 점자 단말기 기능이 필요하지 않은 경우, 위 명령에서 표시된 전체 유닛 이름을 명령어에 대체하여 서비스를 중지 및 비활성화한 후 시스템을 재부팅합니다:

sudo systemctl disable --now ModemManager.service
sudo systemctl disable --now brltty.service
sudo systemctl disable --now brltty.path

7. 완료 후 USB ID를 다시 확인하고 printer.cfg의 [mcu] 섹션에 있는 serial:이 실제 출력과 일치하는지 확인합니다.

관련 설정 참고: MCU ID 설정.

Lost communication with MCU

오류 정보: Klipper와 MCU 간의 통신이 중단되었습니다. 로그에 Lost communication with MCU, Lost communication with mcu 또는 유사한 메시지가 나타날 수 있습니다.

일반적인 상황: 귀환 또는 이동 중에 리미트 스위치가 트리거되면 메인보드 또는 툴보드 연결이 끊어집니다. 전원을 다시 켜면 다시 연결됩니다.

일반적인 원인:

• 리미트 스위치 배선이 잘못되어 트리거 시 신호 핀이 전원 또는 접지와 비정상적으로 단락됩니다.
• 3선식 리미트, 광학 리미트 또는 홀 리미트 사용 시 전원, 접지, 신호선 순서가 잘못 연결되었습니다.
• 리미트 케이블 피복이 벗겨지거나, 케이블이 눌리거나, 케이블 체인 이동 중 단락이 발생합니다.
• 리미트 트리거 순간 메인보드 전원 공급이 불안정해져 MCU가 재시작되거나 USB/CAN 통신이 중단됩니다.
• MCU와 호스트 시스템 간 USB/CAN 통신 케이블이 강한 간섭원 근처를 지나가며, 리미트 트리거나 모션 시 연결 끊김이 더 쉽게 발생합니다.
• 설정의 리미트 핀이 실제 배선과 일치하지 않아 잘못된 인터페이스가 트리거됩니다.

진단 방법:

전원 차단 작업

리미트 케이블을 뽑거나, 배선 순서를 확인하거나, 케이블 체인 배선을 확인하거나, 멀티미터로 도통/저항을 측정하기 전에 프린터를 완전히 끄고 전원 공급을 차단하십시오. 멀티미터 저항/도통 모드는 전원이 차단된 상태에서만 사용해야 하며, 전원이 켜진 상태에서 저항을 측정하거나 단락 테스트를 수행해서는 안 됩니다.

1. 전원을 차단한 후 리미트 스위치 배선 순서, 특히 3선식 리미트의 VCC, GND, Signal이 잘못 연결되었는지 확인합니다.
2. 전원을 차단한 후 해당 리미트 케이블을 일시적으로 분리하고, 다시 장착한 후 전원을 켜서 메인보드가 여전히 연결이 끊어지는지 테스트합니다.
3. 전원을 차단한 후 멀티미터 도통/저항 모드를 사용하여 리미트 트리거 전후에 단락이 있는지 확인하고, 신호 핀이 전원에 연결되었는지 중점적으로 확인합니다.
4. 케이블 체인, 커넥터 및 케이블 굽힘 위치를 검사하여 트리거나 이동 시 케이블이 눌려 단락되지 않는지 확인합니다.
5. MCU와 호스트 시스템 간 USB/CAN 통신 케이블을 모터선, 히터선, 히트베드선 및 전원선에서 최대한 멀리 배치합니다.
6. 기기 케이스, 전원 공급 장치 또는 차폐가 제대로 접지되지 않은 경우 간섭에 더 취약할 수 있습니다. 제조사가 제공한 접지 지점과 콘센트 상태만 확인하고, 전원 공급 장치를 직접 분해하거나 주 전원 접지선을 변경하지 마십시오.
7. 설정의 리미트 핀이 메인보드 문서 및 실제 배선과 일치하는지 확인합니다.
8. 문제 해결 후 QUERY_ENDSTOPS를 실행하여 리미트 상태가 open에서 TRIGGERED로 정상적으로 변경되는지 확인합니다.

관련 설정 참고: 리미트 관련, 전원 배선 설명.

MCU Protocol error

오류 정보: MCU 프로토콜 오류입니다. 로그에 MCU Protocol error, Unknown command 또는 Command format mismatch가 나타날 수 있습니다.

Loading...

일반적인 원인:

• 호스트 시스템의 Klipper는 업데이트했지만 메인보드 또는 툴보드 펌웨어를 다시 컴파일하여 플래시하지 않았습니다.
• 메인보드, 툴보드, EDDY, ADXL 등 주변기기 MCU의 펌웨어 버전이 호스트 시스템의 Klipper와 일치하지 않습니다.
• 맞춤형 시스템 또는 타사 플러그인을 사용하여 Klipper 호스트 측과 MCU가 지원하는 명령이 일치하지 않습니다.

해결 방법:

1. 최근에 Klipper, 시스템 이미지 또는 플러그인을 업데이트했는지 확인합니다.
2. 모든 MCU의 Klipper 펌웨어를 다시 컴파일하여 플래시합니다.
3. 툴보드, EDDY, ADXL 등 주변기기 MCU인 경우 해당 주변기기 펌웨어도 함께 업데이트합니다.
4. 맞춤형 시스템을 사용하는 경우 해당 시스템이 현재 Klipper 버전을 지원하는지 확인합니다.
5. 플래시 완료 후 FIRMWARE_RESTART를 실행하고 다시 연결하여 테스트합니다.

특별 FAQ

항목	시작점
설정 충돌, 매개변수 해석, SAVE_CONFIG	설정 관련 오류
알 수 없는 명령, 매크로 템플릿, 슬라이서 시작 G-code	설정 관련 오류
운동, 귀환, 리미트, 프로브, 메쉬 레벨링	운동, 리미트 및 레벨링 오류
온도, 가열, 압출, 필라멘트 감지	온도, 가열 및 압출 오류
성능, 타임아웃, 펌웨어, 시스템 서비스	시스템, 성능 및 서비스 오류
G2/G3, 호 피팅, 슬라이서 경로 정밀도	호 피팅 권장사항
TMC 드라이버 통신, 과열, 코일 문제	TMC 오류 진단
CAN 네트워크, UUID, bytes_invalid	CAN 네트워크 및 ID 검색
가속도계 및 공진 테스트	가속도계 테스트 및 보정
EDDY 와전류 프로브	EDDY 문제 모음