본문으로 건너뛰기

시스템, 성능 및 서비스 오류

이 페이지에서는 통신 타임아웃, MCU 타이머 오류, 호스트 성능, 펌웨어 플래싱 및 Klipper 서비스 시작 관련 문제를 정리합니다.

귀환(홈) 타임아웃 문제​

오류 메시지: 귀환 과정에서 Communication timeout during homing, Error during homing xxx 발생. 다중 MCU Z축 귀환 시나리오에서 흔히 발생합니다.

일반적인 원인:

  • 호스트 부하가 높음. KlipperScreen, 카메라 스트림 등이 동시에 실행됨.
  • 귀환 시 여러 축 모터가 동시에 작동하여 큰 전류 구동 신호가 CAN/USB 통신선에 결합되어 통신이 중단됨.
  • 다중 MCU 통신 응답이 불안정함.
  • CAN/USB 통신선 품질 문제 또는 배선 상태 불량.

해결 방법:

전원 차단 작업

CAN/USB 배선 재정리, 차폐층 확인 또는 접지 확인 전에 프린터를 완전히 종료하고 전원 공급 장치를 분리하십시오. 전원 접지선, AC 배선 또는 전원 공급 장치 내부 구조를 임의로 변경하지 마십시오.

  1. 먼저 전자기 간섭을 배제합니다: CAN/USB 선이 모터 선, 히터 선과 분리되어 배선되었는지 확인하고, CAN 네트워크 구성 및 ID 검색 의 간섭排查 단계를 참조하십시오.
  2. TRSYNC_TIMEOUT 타임아웃 매개변수를 조정하거나 KlipperScreen을 임시로 비활성화해 봅니다. 자세한 내용은 귀환 타임아웃 문제를 참조하십시오.
  3. 기계 접지 및 차폐층 접지가 정상인지 확인합니다.

MCU 'mcu' shutdown: Stepper too far in past​

오류 메시지: Klipper가 MCU로 보내려고 계획한 스테퍼 이벤트가 현재 시간보다 뒤처져 있어 MCU가 예정된 시간에 이러한 모션 명령을 실행할 수 없으며, 프린터는 shutdown 상태가 됩니다.

Loading...

오류 원인: 이는 일반적으로 특정 고정 구성 항목 때문이 아니라 호스트 측 모션 계획, MCU 스테퍼 출력 또는 통신 스케줄링이 처리하지 못해 발생하는 결과입니다. 호스트 부하가 높음, 인쇄 속도/가속도 과다, 스테퍼 마이크로스테핑 과다, 다중 MCU 통신 지연, USB/CAN 통신 품질 불량, 매크로 또는 G-code가 짧은 시간에 대량의 모션 명령을 생성하는 경우 등이 이 문제를 유발할 수 있습니다.

참조 시나리오: 다중 지점 베드 메시(scan) 수행 시 [bed_mesh]의 probe_count가 너무 크게 설정되고 동시에 높은 mesh_pps가 구성된 경우, 과밀한 그리드 데이터가 생성되어 호스트 계산 및 모션 계획 부하가 증가할 수 있습니다. 이는 일반적인 시나리오 중 하나일 뿐입니다. 베드 메시가 없더라도 시스템 부하 또는 통신 지연이 증가하는 다른 상황에서도 Stepper too far in past가 나타날 수 있습니다.

인쇄 재개 후 정체 시나리오: 이 오류는 PAUSE / RESUME, 필라멘트 부족 복구 또는 정전 후 재개 이후에도 발생할 수 있습니다. 일반적인 로그 패턴은 다음과 같습니다: 재개 후 Stats 행의 buffer_time이 약 1s에서 0.2s 수준으로 급감하고, sd_pos가 거의 증가하지 않으며(인쇄 진행률 정체), 하지만 sysload는 높지 않고 MCU 연결 끊김도 없습니다. 이는 재개 후 모션 명령이 스테퍼 버퍼를 지속적으로 채우지 못해 프린터가 "작동은 시작했지만 거의 움직이지 않고" shutdown 상태가 된다는 것을 의미합니다.排查 시 재개/이어서 인쇄 매크로(resume_gcode, start_gcode)가 재개 순간에 비정상적인 대형 이동 또는 빼기 명령을 보냈는지, 그리고 재개 전에 이미 통신 재전송(bytes_retransmit 증가)이 있었는지 중점적으로 확인하십시오.

해결 방법:

  1. 먼저 klippy.log에서 오류 발생 전의 Stats 행을 확인하여 CPU 점유율 높음, bytes_retransmit, bytes_invalid, Timer too close, MCU 연결 끊김 또는 큐 이상이 동시에 있는지 확인합니다.
  2. 카메라 스트림, KlipperScreen, 원격 제어 플러그인 및 기타 높은 점유율 서비스를 임시로 비활성화하여 호스트 부하를 낮춘 후 다시 테스트합니다.
  3. 인쇄 속도, 가속도 및 스테퍼 마이크로스테핑을 낮추고 오류가 사라지는지 확인합니다.
  4. 오류가 다중 지점 베드 메시 과정에서 발생하는 경우 [bed_mesh]의 probe_count를 줄여 예를 들어 7,7 또는 9,9로 변경하여 테스트합니다.
  5. 높은 mesh_pps가 구성된 경우 해당 구성을 낮추거나 삭제합니다. 예: mesh_pps: 2,2로 변경.
  6. USB/CAN 통신 품질을 확인합니다. CAN을 사용하는 경우 큐 길이, 종단 저항, 배선 순서, 전원 공급 및 펌웨어 CAN 속도를 확인합니다.
  7. 오류 발생 전에 실행 중인 매크로 또는 G-code를 확인하여 매크로 루프, 과밀한 짧은 선분 또는 비정상적인 스크립트가 짧은 시간에 많은 모션 명령을 보내지 않도록 합니다.

관련 구성 참조: 매크로 소개, 일반 디버그 지시어.

MCU 'mcu' shutdown: Timer too close​

오류 메시지: MCU 타이머가 너무 근접하여 시스템 타임아웃이 발생함.

Loading...

오류 원인: 하위 컴퓨터 처리 부하 과다, 호스트 응답 타임아웃, 인쇄 속도 과다, 마이크로스테핑 과다, 시스템 시간 동기화 간섭 또는 MCU 통신선 간섭이 이 문제를 유발할 수 있습니다.

최근 일반적인 시나리오:

  • M600, PAUSE, RESUME, 필라멘트 부족 감지 또는 교체 매크로가 일정 시간 대기 후 인쇄를 재개한 다음 Timer too close가 발생함.
  • EDDY / TAP / CAN 툴보드가 Z 귀환, Z_TILT_ADJUST, QUAD_GANTRY_LEVEL 또는 베드 메시에 참여할 때 로그에 CAN 재전송, I2C 읽기 이상 또는 호스트 부하 스파이크가 동시에 나타남.
  • 다중 툴헤드, 다중 CAN 노드 또는 저성능 호스트에서 카메라, KlipperScreen, 원격 제어 플러그인을 동시에 실행할 때 스케줄링 여유가 부족함.

해결 방법:

  1. 스테퍼 모터 마이크로스테핑을 낮추어 MCU 펄스 처리 부담을 줄입니다.
  2. 인쇄 속도와 가속도를 낮추고 문제가 사라지는지 확인합니다.
  3. 호스트 부하, 전원 공급 및 USB/CAN 통신 품질을 확인합니다.
  4. 전원을 차단한 후 MCU와 호스트 간 통신선이 모터 선, 히터 선, 히트베드 선 또는 전원 선에 가까이 있는지 확인하고, 필요한 경우 다시 배선하거나 차폐된 통신선으로 교체합니다.
  5. 기계 접지를 확인할 때는 제조사가 제공하는 접지점과 콘센트 상태만 확인하고, 전원 공급 장치를 직접 분해하거나 AC 접지선을 변경하지 마십시오.
  6. 문제가 귀환 단계에서 발생하는 경우 귀환 타임아웃 문제를 참조하십시오.
  7. M600 또는 필라멘트 부족 복구 후 문제가 발생하는 경우 매크로에서 PAUSE가 중복되었는지, 필라멘트 부족 센서가 교체 과정에서 오작동했는지, SAVE_GCODE_STATE / RESTORE_GCODE_STATE 이름이 일치하는지 확인합니다.
  8. EDDY TAP, Z 틸트 또는 갠트리 레벨링 중 문제가 발생하는 경우 먼저 EDDY TAP 모드 디버그 방법을 참조하거나 EDDY 문제 모음에 따라排查합니다.
  9. 문제가 지속되면 호스트 시스템 또는 펌웨어를 다시 플래싱하는 것을 고려합니다.

관련 구성 참조: 일반 디버그 지시어, 귀환 및 방향 보정 가이드.

MCU shutdown: Missed scheduling of next digital out event​

오류 메시지: MCU 'xxx' shutdown: Missed scheduling of next digital out event.

오류 원인: Klipper 호스트 측에서 히터, 팬 등의 디지털 출력을 켠 후 MCU는 제때 다음 스케줄링과 확인을 받아야 합니다. 호스트 부하가 높음, 시스템 스케줄링 지연, USB/CAN 통신 불안정 또는 CAN 버스 큐 이상이 있으면 MCU가 다음 디지털 출력 이벤트를 제때 수신하지 못해 shutdown 상태가 됩니다.

주의

이 오류는 히터 출력 스케줄링과 관련이 있습니다. 온도 보호 끄기, verify_heater 비활성화 또는 안전 구성 삭제로 오류를 우회하지 마십시오. 먼저 호스트 부하와 통신 품질을排查하십시오.

해결 방법:

  1. 먼저 klippy.log에서 이 오류 앞의 Stats 행을 확인하여 bytes_retransmit, bytes_invalid, Timer too close 또는 MCU 연결 끊김 기록이 동시에 있는지 확인합니다.
  2. 호스트 부하를 낮추고 카메라 스트림, KlipperScreen, 원격 제어 플러그인 또는 기타 높은 점유율 서비스를 임시로 비활성화합니다.
  3. USB/CAN 통신 품질을 확인합니다. CAN을 사용하는 경우 CAN0 큐 길이, 종단 저항, 배선 순서, 전원 공급 및 펌웨어 CAN 속도를 확인합니다.
  4. 인쇄 속도, 가속도 및 스테퍼 마이크로스테핑을 낮추고 문제가 사라지는지 확인합니다.
  5. 가열 시에만 발생하는 경우 히트베드, 핫엔드, 팬 및 전원 부하를 동시에 확인합니다. 전원 공급 장치를 직접 분해하거나 AC 히트베드 고전압 배선을 점검하지 마십시오.
  6. 문제가 CAN 툴보드에서 발생하는 경우 CAN 오류排查에 따라 계속 처리합니다.

관련 구성 참조: 일반 디버그 지시어, CAN 네트워크 및 ID 검색.

Rescheduled timer in the past​

오류 메시지: 로그에 Rescheduled timer in the past 또는 유사한 경고가 나타남.

오류 원인: 호스트 시스템 클럭 문제 또는 CPU 부하가 높아 타이머 작업의 실제 실행 시간이 계획된 시간보다 늦어짐.

해결 방법:

  1. NTP 동기화가 활성화된 경우 임시로 비활성화하고 테스트합니다.
  2. 호스트에서 실행되는 다른 서비스 부하를 줄입니다. 예: 불필요한 웹 인터페이스, 카메라 스트림 등을 끕니다.
  3. 가상 머신에서 실행 중인 경우 물리 머신으로 마이그레이션하거나 더 안정적인 클럭 소스를 사용하는 것을 고려합니다.
  4. 호스트 CPU 사용률을 확인합니다: htop으로 klippy 프로세스에 비정상적인 CPU 점유율이 있는지 확인합니다. 관련 설정 참고: 常用调试指令。

MCU 'mcu' shutdown: Move queue overflow​

오류 메시지: MCU 'mcu' shutdown: Move queue overflow.

오류 원인: MCU 모션 큐가 가득 차서 호스트 측에서 모션 계획 및 상태를 MCU에 적시에 동기화하지 못했습니다. 호스트 성능 부족, 짧은 시간 내的大量 미세 이동, Klipper 호스트와 MCU 펌웨어 버전 불일치, 또는 제조사 맞춤형 Klipper가 각 이동 명령에 동기화 디스크 쓰기, 정전 후 이어쓰기 등의 차단 로직을 추가한 경우에 흔히 발생합니다.

일반적인 판단 포인트:

  • klippy.log에서 Git version과 Loaded MCU 'xxx' ... version의 기본 버전 차이가 큰 경우.
  • 로그에 dirty, 서드파티 klippy/extras 파일, 제조사 맞춤형 정전 후 이어쓰기 또는 비공식 Klipper가 나타나는 경우.
  • 동일한 G-code 파일이 비슷한 위치에서 실패하고, 모델에 많은 짧은 선분, 조밀한 서포트, 나선형 Z-hop 또는 복잡한 경로가 포함된 경우.
  • 저성능 호스트에서 카메라, 화면, 원격 제어 또는 기타 고부하 서비스를 동시에 실행하는 경우.

해결 방법:

  1. 전체 klippy.log를 확인하여 더 이른 Timer too close, CAN 연결 끊김, bytes_invalid 또는 온도/TMC 오류가 있는지 먼저 확인합니다.
  2. Klipper 업데이트 후 모든 MCU 펌웨어를 다시 컴파일하고 플래시하여 호스트와 메인보드, 툴보드 펌웨어 버전이 일치하는지 확인합니다.
  3. 카메라 스트림, KlipperScreen, 원격 제어 플러그인 및 기타 리소스 점유율이 높은 서비스를 일시적으로 끄고 다시 테스트합니다.
  4. 인쇄 속도, 가속도, 스테퍼 마이크로스테핑을 낮추거나 슬라이서에서 곡선 정밀도, 서포트 복잡성 및 짧은 선분 밀도를 낮춥니다.
  5. 제조사 맞춤형 정전 후 이어쓰기, 자동 높이 기록 또는 서드파티 플러그인을 사용하는 경우 먼저 오리지널 Klipper를 사용하거나 해당 기능을 끄고 교차 테스트합니다. 일반 고객에게 Klipper 소스 코드를 직접 수정하는 것을 일반적인 절차로 안내하지 마십시오.
  6. 특정 G-code 파일에서만 발생하는 경우 다시 슬라이싱하고 슬라이서가 비정상적으로 조밀한 경로를 출력하는지 확인합니다.

관련 설정 참고: 常用调试指令, 호 호환 권장사항.

stepcompress / syncemitter / flush_handler 내부 오류​

오류 메시지: stepper.error: Internal error in stepcompress, stepcompress ... Invalid sequence, Error in syncemitter 'extruder' step generation, Exception in flush_handler, Flush Handler error.

오류 원인: Klipper가 스텝 펄스를 생성하거나 압축할 때 내부 예외가 발생했습니다. 최근 커뮤니티 사례에서 이러한 문제는 고속 베드 스캔, scanner / EDDY / Cartographer 계열 프로브 플러그인, input_shaper, 복잡한 모션 경로 또는 서드파티 Klipper 수정과 동시에 자주 발생합니다. 반드시 슬라이서 단독 원인은 아니며, 슬라이싱만 다시 해서 근본 원인을 판단해서는 안 됩니다.

해결 방법:

  1. 전체 klippy.log를 보존하고 해당 오류 전후의 Python Traceback, 실행 중인 명령 및 Stats 행을 중점적으로 확인합니다.
  2. 오류가 BED_MESH_CALIBRATE, QUAD_GANTRY_LEVEL 또는 scanner 베드 스캔 중에 발생하는 경우 먼저 스캔 속도, 포인트 수, 보간 밀도 및 플러그인 스캔 매개변수를 낮춥니다.
  3. 서드파티 scanner, 자동 속도 조절, 자동 레벨링 강화, 매크로 패키지 또는 제조사 수정을 일시적으로 비활성화하고 오리지널 Klipper로 다시 테스트합니다.
  4. Klipper 업데이트 후 모든 MCU 펌웨어를 다시 플래시하고 주변 장치 펌웨어가 호스트 Klipper 버전과 일치하는지 확인합니다.
  5. 동일한 모델이 반복적으로 트리거되면 다시 슬라이싱하고 짧은 선분 밀도를 낮춥니다. 다시 슬라이싱한 후에도 무작위로 발생하면 호스트 부하, 모션 매개변수 및 플러그인 호환성을 계속해서 점검합니다.
  6. 프린터에 비정상적인 움직임, 낙차 또는 충돌 위험이 있는 경우 즉시 비상 정지하고 재홈으로 복귀하며 원래 작업을 계속 재개하지 마십시오.

관련 설정 참고: 모션, 리미트 및 레벨링 오류, EDDY 문제 모음.

연결 중 내부 오류 / has no attribute​

오류 메시지: Klipper 업데이트 후 시작이 완료되지 않고 로그에 Unhandled exception during connect, Internal error during connect가 나타나며 Traceback 끝부분이 다음과 유사할 수 있습니다:

AttributeError: 'MCU' object has no attribute '_serialport'

다른 has no attribute, got an unexpected keyword argument 또는 모듈 인터페이스 누락 메시지가 표시될 수도 있습니다.

오류 성격: 이 오류는 Klipper가 연결 초기화 단계에서 Python 코드를 실행할 때 예외가 발생했음을 나타냅니다. 최근 커뮤니티 사례에서 Traceback이 서드파티 klippy/extras/ 모듈을 가리키는 경우, 일반적으로 Klipper가 내부 인터페이스를 업데이트했지만 이전 버전 확장 또는 제조사 맞춤형 모듈이 여전히 기존 인터페이스를 호출하고 있기 때문입니다. 일반적으로 MCU 펌웨어 손상이 아니며, 먼저 시리얼 포트 케이블 고장으로 처리해서는 안 됩니다.

일반적인 원인:

  • Klipper는 업데이트되었지만 서드파티 프로브, 필라멘트 교체, 매크로 패키지 또는 기타 확장이 동기화되지 않은 경우.
  • 제조사 맞춤형 Klipper 분기를 사용하면서 오리지널 Klipper에만 맞는 확장을 혼용한 경우.
  • 확장 업데이트 시 파일이 불완전하여 이전/신규 Python 파일이 동시에 잔존하는 경우.
  • Traceback이 실제로 설정 파일, 변수 파일 또는 오리지널 모듈의 다른 예외를 가리키며 확장 호환성 문제가 아닌 경우.

해결 방법:

  1. 전체 klippy.log를 저장하고 첫 번째 Unhandled exception during connect부터 Traceback을 아래로 읽으며 마지막 예외와 예외 직전의 마지막 klippy/extras/xxx.py 파일 이름을 기록합니다.
  2. 로그 시작 부분의 Git version, Modified files 및 Untracked files를 확인합니다. 예외 파일이 서드파티 확장에 속하면 해당 확장의 유지 관리 설명에 따라 현재 Klipper에 맞는 버전으로 업데이트합니다.
  3. Traceback이 가리키는 서드파티 모듈 또는 관련 include를 일시적으로 비활성화하고 재시작하여 오리지널 Klipper가 정상적으로 연결되는지 확인합니다. Python 속성 누락을 처리하기 위해 MCU를 반복적으로 플래시하지 마십시오.
  4. 제조사 맞춤형 Klipper를 사용하는 경우 해당 시스템이 명시적으로 지원하는 업데이트 방식을 사용해야 합니다. 오리지널 Klipper, 맞춤형 분기 및 다른 버전의 확장을 임의로 혼합하지 마십시오.
  5. Traceback이 오리지널 Klipper 파일만 가리키고 Modified files / Untracked files에 이상이 없으면 현재 안정 버전으로 업데이트한 후 전체 로그를 다시 수집하고 Klipper 커뮤니티에 재현 가능한 절차를 보고합니다.
  6. 다운그레이드는 버전 호환성 문제인지 확인하기 위한 단기 확인 용도로만 사용할 수 있습니다. 장기적인 해결책은 확장을 업데이트하거나 호환되지 않는 모듈을 제거하는 것이며, 알려진 너무 오래된 버전에 장기간 머물지 마십시오.

연결 준비 콜백 중 내부 오류: 변수 저장 실패​

오류 메시지: Klipper 시작 직후 shutdown 상태가 되고 로그에 다음 키워드가 나타납니다:

Unable to save variable
reactor.ReactorError: Internal error - reactor pause disabled
Unhandled exception during ready callback
Internal error during ready callback: Unable to save variable

오류 성격: Unable to save variable는 변수 쓰기 실패의 결과 메시지일 뿐입니다. 최근 커뮤니티 사례에서 reactor pause disabled, ready callback과 동시에 나타나는 경우, 일반적으로 서드파티 확장이 Klipper의 ready 콜백 단계에서 SAVE_VARIABLE를 호출하여 최신 버전의 비동기 쓰기 메커니즘과 호환되지 않기 때문입니다. 이는 저장 장치 손상이나 MCU 연결 끊김과 동일하지 않습니다.

일반적인 원인:

  • Klipper 업데이트 후 이전 버전 서드파티 확장이 여전히 시작 콜백에서 변수를 동기적으로 쓰는 경우.
  • 확장 또는 제조사 맞춤형 모듈이 동기화되지 않았고 Traceback이 해당 klippy/extras/ 파일을 가리키는 경우.
  • 로그에 reactor pause disabled가 없으면 변수 파일 경로 오류, 디렉터리 읽기 전용, 디스크 공간 부족 또는 권한 이상일 수도 있습니다.

해결 방법:

  1. klippy.log에서 첫 번째 Unable to save variable부터 전체 Python Traceback을 읽고, 마지막 shutdown 행만 보지 말고 먼저 나타나는 서드파티 모듈 경로와 예외 원문을 기록합니다.
  2. reactor pause disabled와 서드파티 확장 경로가 동시에 나타나면 먼저 해당 확장을 현재 Klipper에 맞게 업데이트한 후 Klipper를 재시작합니다. 확장에 호환 버전이 없으면 확장 유지 관리자에게 문의합니다.
  3. Traceback이 가리키는 서드파티 확장 또는 관련 include를 일시적으로 비활성화하고 다시 테스트하여 오리지널 Klipper가 정상적으로 시작되는지 확인할 수 있습니다. 일반적인 문제 해결 절차로 Klipper 핵심 소스 코드를 직접 수정하지 마십시오.
  4. Traceback에 Permission denied, Read-only file system 또는 No space left on device가 표시되면 다음 명령을 실행하여 디스크 공간과 변수 파일 권한을 확인한 후 실제 경로 또는 권한을 수정합니다. chmod 777로 무관한 디렉터리 권한을 넓히지 마십시오.
df -h
ls -l ~/printer_data/config/
  1. Klipper 다운그레이드는 단기간 호환성 검증용으로만 사용해야 하며 장기적인 해결책이 되어서는 안 됩니다. 문제를 확인한 후에는 지원되는 Klipper 버전으로 복원하고 해당 확장 기능을 업데이트하십시오.

Internal error on command​

오류 메시지: Internal error on command:"XXX", Klipper가 shutdown 상태로 전환됩니다.

일반적인 원인:

  • 매크로 또는 G-code 명령이 Klipper 내부 Python 예외를 트리거했습니다.
  • 구성 파일에 잘못된 매크로 참조 또는 Jinja2 템플릿 구문 오류가 있습니다.
  • Klipper 버전과 구성 파일 형식이 호환되지 않습니다.
  • G-code 파일 이름에 특수 문자가 포함되어 인코딩 오류가 발생합니다.
  • stepcompress, syncemitter 또는 flush_handler 오류로 명령 실행이 중단되었습니다.

해결 방법:

  1. klippy.log에서 Internal error 아래의 전체 Python Traceback을 확인합니다.
  2. Traceback을 통해 어떤 구성 파일 또는 매크로에 문제가 있는지 찾습니다.
  3. 일반적인 원인으로는 [gcode_macro]의 Jinja2 템플릿 구문 오류, [respond] 구성 누락, [virtual_sdcard] 경로 오류가 있습니다.
  4. 오류가 SDCARD_PRINT_FILE과 관련되고 ascii codec can't decode가 표시되면 G-code 파일 이름을 영문, 숫자, 밑줄 또는 하이픈으로 변경하십시오.
  5. Traceback에 stepcompress, syncemitter 또는 flush_handler가 나타나면 stepcompress / syncemitter / flush_handler 내부 오류를 참조하여 계속 확인하십시오.

관련 구성 참조: 매크로 소개, 구성 수정 설명.

Unable to open file / SD busy​

오류 메시지: 파일 인쇄 시 Unable to open file, Unable to get file list, SD busy, SD write not supported, SDCARD_RESET_FILE cannot be run from the sdcard가 표시됩니다.

일반적인 원인:

  • G-code 파일이 존재하지 않거나, 파일 이름이 변경되었거나, 업로드가 완료되지 않았습니다.
  • [virtual_sdcard] path가 잘못된 디렉터리를 가리키고 있습니다.
  • 파일 권한이 비정상적이어서 Klipper 사용자가 읽을 수 없습니다.
  • 파일 이름에 특수 문자가 포함되어 일부 프론트엔드 또는 시스템 경로 처리에서 오류가 발생합니다.
  • 인쇄 중이거나 파일을 읽는 중에 가상 SD를 열기, 선택, 재설정 또는 쓰기 명령을 다시 실행했습니다.
  • Klipper 소스 코드 디렉터리, 구성 디렉터리 또는 기타 G-code가 아닌 디렉터리를 [virtual_sdcard] path로 잘못 설정했습니다.

해결 방법:

  1. 웹 인터페이스에서 G-code 파일을 다시 업로드하고 파일 이름이 인쇄 명령과 일치하는지 확인합니다.
  2. [virtual_sdcard] path가 실제 G-code 저장 디렉터리를 가리키는지 확인합니다.
  3. 디렉터리 권한 확인: ls -la ~/printer_data/gcodes/.
  4. 파일 이름을 영문, 숫자, 밑줄 또는 하이픈으로 변경한 후 다시 테스트합니다.
  5. SD busy가 표시되면 현재 인쇄를 일시 중지하거나 취소하고 다른 매크로가 가상 SD 파일을 조작하고 있지 않은지 확인합니다.
  6. ~/klipper, ~/printer_data/config 또는 시스템 디렉터리를 G-code 저장 디렉터리로 설정하지 마십시오.

관련 구성 참조: 구성 수정 설명.

MCU CRC does not match config / Can not update MCU config​

오류 메시지: MCU 'xxx' CRC does not match config, Can not update MCU 'xxx' config as it is shutdown, Unable to configure MCU 'xxx'.

판단 핵심: Can not update MCU 'xxx' config as it is shutdown은 일반적으로 최초 근본 원인이 아니라 MCU가 이미 shutdown/error 상태가 된 후 Klipper가 MCU에 다시 연결하거나 재구성할 때 나타나는 후속 오류입니다. 로그의 마지막 줄만 보지 말고 더 위로 올라가 더 이른 시점의 첫 번째 실제 오류를 찾아 확인하십시오.

해결 방법:

  1. FIRMWARE_RESTART를 실행하고, 필요한 경우 전체 장비 전원을 10초간 차단한 후 다시 켭니다.
  2. klippy.log에서 더 이른 시점에 나타난 첫 번째 shutdown, Timer too close, Lost communication, Verify heater, TMC 또는 온도 오류를 확인하고 shutdown을 유발한 근본 원인을 먼저 수정합니다.
  3. 다중 MCU 장비는 각 [mcu], [mcu xxx]의 USB ID 또는 CAN UUID를 개별적으로 확인합니다.
  4. Klipper를 방금 업데이트했다면 모든 MCU 펌웨어를 다시 컴파일하고 플래시합니다.
  5. [mcu host]를 사용하는 경우 klipper-mcu 서비스가 정상적으로 시작되었는지 확인한 후 Klipper를 다시 시작합니다.
  6. 사전 설치 또는 커스텀 Klipper 시스템을 사용하는 경우 로그가 완전하고 Klipper와 MCU 펌웨어 버전 출처가 일치하는지 확인합니다.

MCU 'xxx' shutdown: Command request​

오류 메시지: MCU 'xxx' shutdown: Command request.

일반적인 원인:

  • CAN 툴보드 펌웨어 버전과 호스트 Klipper 버전이 일치하지 않아 호스트가 펌웨어가 지원하지 않는 명령을 전송했습니다.
  • Klipper 또는 시스템 업데이트 후 툴보드 펌웨어를 다시 컴파일하고 플래시하지 않았습니다.
  • 해당 MCU 펌웨어가 컴파일 시 지원하지 않는 기능을 구성했습니다(예: I2C를 활성화하지 않았는데 EDDY / ADXL을 구성).
  • 툴보드 또는 MCU 하드웨어가 손상되었거나 연결이 불안정합니다.

해결 방법:

  1. klippy.log에서 Loaded MCU 'xxx' ... version 및 Git version을 확인하여 버전이 일치하는지 확인합니다.
  2. 오류가 발생한 MCU의 펌웨어를 다시 컴파일하고 플래시합니다. 플래시 방법은 해당 툴보드 제품 문서를 따르십시오.
  3. 다중 MCU 장비는 모든 MCU 펌웨어가 동일한 컴파일에서 생성되었는지 확인합니다.
  4. 플래시 완료 후 FIRMWARE_RESTART를 실행하여 오류가 더 이상 발생하지 않는지 확인합니다.

일반 버전 확인: MCU Protocol error

Shutdown due to M112 command / webhooks request​

오류 메시지: Shutdown due to M112 command 또는 Shutdown due to webhooks request.

해결 방법:

  1. 사용자가 수동으로 비상 정지를 눌렀는지 확인합니다. 만약 그렇다면 위험을 배제한 후 FIRMWARE_RESTART를 실행합니다.
  2. 커스텀 매크로에서 M112, action_emergency_stop, emergency_stop을 검색합니다.
  3. 프론트엔드, 원격 제어 플러그인 또는 자동화 스크립트가 비상 정지 인터페이스를 실수로 트리거했는지 확인합니다.

호스트 성능 부족으로 인한 인쇄 끊김​

오류 메시지: 명확한 오류는 없지만 인쇄 과정에서 간헐적인 멈춤, 압출 끊김이 발생합니다.

해결 방법:

  1. 인쇄 속도와 가속도를 낮춥니다.
  2. 호스트에서 불필요한 Web 서비스, 카메라 스트림 등을 종료합니다.
  3. [bed_mesh]의 probe_count와 mesh_pps를 줄입니다.
  4. 슬라이서가 G2 / G3 호를 출력했다면 호 피팅 권장 사항을 참조하여 조정하거나 비활성화합니다.
  5. 호스트 성능이 실제로 부족하다면 더 강력한 호스트로 교체하는 것을 고려합니다.

호스트 비정상 재시작 / 시스템 충돌​

오류 메시지: 인쇄 중 Klipper / Moonraker가 갑자기 연결이 끊기고 klippy.log가 갑자기 중단되며 명확한 shutdown 근본 원인이 없습니다. Mainsail / Fluidd가 다시 연결된 후 호스트 또는 Klipper가 재시작된 것을 확인합니다.

일반적인 원인:

  • 호스트 전원 공급 부족으로 인쇄 중 USB, 카메라, 화면 또는 팬 부하 변화로 전원이 차단됩니다.
  • 시스템 디스크, TF 카드 또는 eMMC 읽기/쓰기 오류로 로그가 갑자기 중단되거나 파일이 손상됩니다.
  • 호스트 CPU 과열로 시스템 보호 차원에서 클럭 저하, 멈춤 또는 재시작이 발생합니다.
  • USB 역전원 공급 또는 주변기기 전원 경로 이상으로 메인보드, 화면 또는 호스트가 서로 영향을 줍니다.
  • 타사 서비스, 카메라 스트림, AI 플러그인 또는 과도한 웹 연결이 리소스를 점유합니다.

확인 방법:

전원 차단 작업

호스트 전원 케이블, USB 케이블, 화면 케이블, 팬 케이블을 확인하거나 배선을 정리하기 전에 프린터 전원을 완전히 끄고 전원 공급 장치를 분리하십시오. 전원 공급 장치를 분해하거나 AC 배선을 변경하지 마십시오.

  1. 먼저 klippy.log, moonraker.log 및 시스템 로그를 확인하여 Klipper 오류인지 호스트 전체 재시작인지 확인합니다.
  2. 호스트 전원 사양을 확인하고 전류 부족이나 전압 강하가明显的 전원 케이블 사용을 피하십시오.
  3. 시스템 디스크 건강 상태를 확인하고 필요한 경우 신뢰할 수 있는 TF 카드, eMMC로 교체하거나 시스템을 다시 플래시합니다.
  4. 호스트 방열을 확인하고 팬이 정상 작동하며 방열판이 잘 밀착되고 케이스 통풍이 원활한지 확인합니다.
  5. 카메라 스트림, KlipperScreen, 원격 제어 플러그인 및 기타 고부하 서비스를 임시로 종료한 후 인쇄 테스트를 진행합니다.
  6. USB 역전원 공급이 의심되면 완제품 USB 케이블을 우선 교체하거나 전원 절연 기능이 있는 연결 방식을 사용하고, 일반 사용자는 임의로 케이블을 개조하지 마십시오.

일시 중지, 재개 및 상태 저장 알림​

오류 메시지: Print already paused, Print is not paused, resume aborted, Unknown g-code state: PAUSE_STATE.

일반적인 원인:

  • PAUSE를 중복 실행했거나 인쇄가 이미 취소된 후 RESUME을 실행했습니다.
  • 커스텀 일시 중지/재개 매크로에서 SAVE_GCODE_STATE NAME=와 RESTORE_GCODE_STATE NAME= 이름이 일치하지 않습니다.
  • 타사 매크로 패키지와 Mainsail / Fluidd 기본 일시 중지/재개 매크로가 중복 정의되거나 논리 충돌이 발생합니다.
  • 비상 정지, FIRMWARE_RESTART 또는 Klipper 오류 후 기존 일시 중지 상태가 손실되었습니다. 해결 방법:
  1. 현재 인쇄 상태를 확인하고, 일시정지되지 않은 상태에서 RESUME을 실행하지 마십시오.
  2. [pause_resume]이 활성화되어 있는지, 그리고 PAUSE / RESUME / CANCEL_PRINT 매크로가 중복 정의되지 않았는지 확인하십시오.
  3. 매크로 내의 SAVE_GCODE_STATE 및 RESTORE_GCODE_STATE 이름이 완전히 일치하는지 확인하십시오.
  4. Klipper가 이미 오류를 보고하거나 비상 정지된 경우, 인쇄 재개를 계속하지 말고 위험 요소를 제거한 후 다시 시작하는 것이 좋습니다.

Klipper 반복 재시작 (Klippy not connected 반복 깜빡임)​

오류 정보: Mainsail / Fluidd에 Klippy not connected가 반복적으로 표시되고, Klipper가 계속 자동으로 재시작되며 매번 몇 초 내에 종료됩니다. 로그에서 Klipper restarting too fast가 보이거나 재시작할 때마다 klippy.log가 매우 짧을 수 있습니다.

문제 해결 방법:

  1. 먼저 로그 파일의 끝부분을 확인하여 마지막 종료 원인을 확인하십시오:

    tail -100 ~/printer_data/logs/klippy.log

  2. 로그 끝부분이 Python Traceback이면 구성 파일 구문 분석 또는 내부 예외로 인한 충돌을 의미합니다.

  3. Klipper restarting too fast만 보고 근본 원인을 판단하지 마십시오. 이는 일반적으로 systemd가 반복적으로 실행에 실패한 결과일 뿐이므로, klippy.log의 첫 번째 실제 오류를 우선적으로 처리하십시오.

  4. 로그 끝부분에 MCU Protocol error, Unknown command 등이 표시되면 펌웨어 버전이 일치하지 않는 것이므로 MCU 펌웨어를 다시 컴파일하여 플래시해야 합니다.

  5. 로그가 매우 짧고 명확한 오류가 없다면, 최소 구성 이분법을 사용하여 위치를 특정하십시오.

  6. include 파일에 순환 참조가 있는지 확인하십시오.

실행 중 처리되지 않은 예외 (Unhandled exception during run)​

오류 정보: Unhandled exception during run이 표시되고, 프런트엔드에 Printer is shutdown이 표시되며, 로그에는 Python Traceback이 동반됩니다.

일반적인 원인:

  • 이는 독립적인 하드웨어 오류가 아니라 Klipper 메인 루프가 처리되지 않은 예외를 포착했을 때 발생하는 일반적인 오류입니다. 실제 원인은 Traceback 위쪽의 구체적인 오류를 확인해야 합니다.
  • 일반적인 트리거 원인: TMC UART 읽기 실패(Unable to read tmc uart 'stepper_x' register DRV_STATUS), CAN 통신 중단, 매크로 템플릿 런타임 오류, 타사 확장 모듈 예외.
  • Klipper 업그레이드 후 이전 구성 또는 이전 매크로가 새 버전 API와 호환되지 않음.
  • 상위 컴퓨터 Python 환경 손상 또는 종속성 누락.

해결 방법:

  1. 전체 klippy.log를 열고 Unhandled exception during run 위쪽의 Traceback을 검색하여 첫 번째 실제 오류(예: Unable to read tmc uart, CanError, TypeError 등)를 찾으십시오.
  2. 실제 오류가 TMC UART 통신 실패인 경우 TMC 오류 문제 해결에 따라 배선 및 구성을 확인하십시오.
  3. CAN 통신 예외인 경우 CAN 오류 문제 해결에 따라 버스 상태를 확인하십시오.
  4. Traceback이 특정 매크로 또는 확장 모듈을 가리키는 경우 해당 모듈이 현재 Klipper 버전과 호환되는지 확인하고, 필요한 경우 업데이트하거나 일시적으로 비활성화하십시오.
  5. Klipper 업그레이드 후 이 오류가 발생하면 Config_Changes.md에 구성 마이그레이션 요구 사항이 있는지 확인하십시오.
  6. Unhandled exception during run 이 한 줄만 보고 문제를 판단하지 마십시오. 이것은 단지 외부 껍데기일 뿐이며, 실제 원인은 항상 Traceback에 있습니다.

다음 하드 PWM 이벤트 예약 누락 (Missed scheduling of next hard pwm event)​

오류 정보: MCU 'mcu' shutdown: Missed scheduling of next hard pwm event.

일반적인 원인:

  • Missed scheduling of next digital out event와 동일한 유형으로, 상위 컴퓨터가 기한 내에 PWM 이벤트를 MCU로 전송하지 못한 것입니다.
  • 상위 컴퓨터 CPU 부하가 높음(카메라 스트림, KlipperScreen, 다수의 플러그인 동시 실행).
  • 레이저 모듈 또는 고주파 PWM 도구 사용 시 cycle_time 설정이 너무 작아 스케줄링 간격이 매우 짧아짐.
  • CAN 버스 지연이 너무 높아 이벤트가 전송 중에 시간 초과됨.

해결 방법:

  1. 상위 컴퓨터 CPU 부하를 확인하고, 카메라, KlipperScreen 및 기타 불필요한 서비스를 일시적으로 끈 후 다시 테스트하십시오.
  2. 레이저 또는 PWM 도구를 사용하는 경우 cycle_time을 적절히 늘리십시오(예: 0.00002에서 0.0001로 변경).
  3. CAN 버스 상태를 확인하고 tx_error, bytes_retransmit이 지속적으로 증가하지 않는지 확인하십시오.
  4. 고품질 USB 케이블로 교체하거나 CAN 전송 속도를 낮추어(1M에서 500K로) 테스트하십시오.
  5. 저성능 상위 컴퓨터(오래된 휴대폰, 저가형 개발 보드)에서는 동시에 실행되는 서비스 수를 줄이는 것이 좋습니다.

관련 오류: Missed scheduling of next digital out event

스테퍼 활성 상태에서 시간 재설정 불가 (Can't reset time when stepper active)​

오류 정보: MCU 'mcu' shutdown: Can't reset time when stepper active, 인쇄 중 Klipper 자동 재시작이 자주 동반됨; 재시작 후 TMC stepper_x failed to init: Timeout on wait for 'tmcuart_response' response가 이어서 나타날 수 있음.

일반적인 원인:

  • 이는 독립적인 하드웨어 오류가 아니라 상위 컴퓨터가 스테퍼 모터가 여전히 움직이는 동안 스테퍼 클록 기준을 재설정하려고 시도하여 MCU가 거부하고 shutdown 보호 모드로 전환되는 것입니다.
  • 가장 일반적인 트리거 원인은 Klipper 서비스가 인쇄 도중 자발적으로 재시작되는 경우(상위 컴퓨터 측)입니다. 로그에서 Starting Klippy...가 직전까지 인쇄 중이던 Stats 통계 행 바로 다음에 나타나는 것을 볼 수 있습니다.
  • Moonraker에 연결된 일부 클라이언트 또는 플러그인이 서비스 재시작을 반복적으로 요청함.
  • 상위 컴퓨터의 전원 공급 부족, 과열, 메모리 고갈 등으로 시스템이 klipper 서비스를 종료한 후 다시 시작함.

해결 방법:

  1. 전체 klippy.log를 열고 Starting Klippy...를 검색하여 Klipper가 인쇄 도중 재시작되었는지, 그리고 마지막 인쇄 통계 행과의 시간 간격을 확인하십시오.
  2. systemctl status klipper.service 및 journalctl -efu klipper를 실행하여 서비스 재시작 기록과 원인을 확인하십시오.
  3. Moonraker에 연결된 클라이언트와 플러그인(카메라 스트림, 타사 플러그인, 사용자 정의 스크립트)을 확인하여 서비스 재시작이나 머신 재부팅을 요청하는 장치가 없는지 확인하십시오.
  4. 상위 컴퓨터의 전원 공급, 방열 및 메모리 사용량을 확인하십시오. 오래된 라즈베리 파이 또는 저성능 개발 보드에서 카메라와 KlipperScreen을 동시에 실행하면 메모리 부족으로 시스템에 의해 종료될 수 있습니다.
  5. 재시작 후 나타나는 Timeout on wait for 'tmcuart_response'는 재시작의 결과이지 근본 원인이 아니므로, 이것 때문에 먼저 TMC 배선을 점검하지 마십시오.

관련 오류: Klipper 반복 재시작, Unhandled exception during run

Loading...