ComfyUI 장애 진단 결정 트리: 문제 원인 분류 요령

ComfyUI 실행 시 에러가 났을 때, 원인을 모른 채 임의로 라이브러리 추가 명령이나 재설치를 감행하는 것은 가장 비효율적인 해결 방식입니다. 본 복구 트리는 수백 건의 실제 연동 문의 해결 사례를 모아 장애 유형을 체계적으로 분류하는 가이드를 제공합니다.

본 가이드 활용 대상

본인이 현재 겪고 있는 장애 유형이나 에러 레이어가 어디인지 정확히 모를 때 본 복구 트리를 사용하십시오. 이미 명확한 예외 모듈 명칭을 알고 있는 경우, 해당 모듈 개별 가이드를 검색해 보시는 것이 해결이 훨씬 빠릅니다.

---

단계 1: ComfyUI 서버가 정상적으로 기동하는가?

웹 브라우저 주소창에 http://127.0.0.1:8188을 입력하고 정상 화면이 반응하는지 검증합니다.

• 예 → ComfyUI 백엔드 코어 엔진은 정상입니다. 단계 2로 진행합니다.
• 아니오 (시작하자마자 까만 창이 바로 꺼짐 등) → 백엔드 가상환경 및 드라이버 레이어를 먼저 복원해야 합니다.
  • 조치: ComfyUI 자주 발생하는 문제 페이지의 시작 오류 해결법을 읽으십시오.
  • 조치: GPU 호환성 가이드를 통해 NVIDIA 드라이버 버전과 CUDA 조합을 확인하십시오.
  • 구동 상세 가이드: 데스크톱 에디션, 포터블 에디션, 수동 Git 설치

단계 2: 워크플로 캔버스에 붉은색 노드가 표시됨

워크플로 JSON을 로드했을 때, 일부 노드 상자가 빨간색 테두리로 비활성화되는 증상.

1단계: 화면에만 임시 표기되는 프론트엔드 장식 노드입니까?

아래 종류 노드들은 서버 백엔드 파이썬에 모듈 등록이 필요 없는 캔버스 전용 뷰어이므로, 빨간색으로 나와도 무시하고 쓰셔도 무방합니다.

• Note, Reroute, MarkdownNote
• Fast Groups Muter (rgthree), Fast Groups Bypasser (rgthree)
• PrimitiveNode, GetNode, SetNode
• workflow> 머리글로 시작하는 모든 로컬 래핑형 노드

2단계: 물리 플러그인 폴더가 실제 드라이브에 실존합니까?

본인 PC의 ComfyUI/custom_nodes/ 하위 경로에 해당 노드의 폴더가 있는지 점검합니다.

• 폴더가 없음 → 올바른 노드를 설치해 줍니다. 획득 방법은 커스텀 노드 안전하게 설치하기 참고.
• 폴더가 있음에도 빨간색 노드로 나옴 → 단계 3으로 진행합니다.

상세 가이드:

• ComfyUI 워크플로의 누락 노드 복구

단계 3: 폴더는 실존하나 노드가 무시됨

custom_nodes 내부에 확실히 폴더가 매칭되는데도 웹 화면에서 해당 노드를 쓸 수 없을 때.

시작 터미널 창을 위로 올려 IMPORT FAILED 경고줄이 기록되었는지 필터링합니다.

• ModuleNotFoundError 경고를 수반한 로드 실패 → 의존성 라이브러리가 유실된 상태입니다.
  • 조치: ComfyUI 작동용 정확한 파이썬 가상환경 경로를 사용해 누락 패키지만 가볍게 보충하십시오.
  • 상세 흐름은 ComfyUI 의존성 충돌 참고.
• AttributeError 또는 ImportError 내부 API 충돌 실패 → 소스코드 호환성(버전 정합) 오류입니다.
  • 노드의 버전이 현재 깔려 있는 ComfyUI 핵심 빌드 규격과 맞지 않습니다.
  • 해당 노드 폴더 경로로 들어가 git pull로 코드를 최신화하거나 임시 보완 패치를 해야 합니다 (무작정 패키지 pip 명령을 실행하지 마십시오).
• 아무 경고도 찍히지 않았는데 노드가 미등록으로 나옴 → 노드 이름 개정 오류입니다.
  • 플러그인이 업데이트되면서 내부 등록 명칭을 수정하여 옛날 워크플로가 감지하지 못하는 상태입니다. 캔버스에서 해당 노드를 삭제하고 검색하여 재생성해 줍니다.

상세 가이드:

• ComfyUI 플러그인 가져오기 실패 복구

단계 4: 노드는 정상 색상이나 실행(Queue) 즉시 크래시 발생

노드 색상은 일반적인데 실행(렌더링 시작) 단추를 누르면 프로세스가 정지하거나 오류 창이 나옴.

• 에러 로그 문자열에 학습 모델 파일 경로가 찍힘 → 패키지 오류가 아닌 학습 모델 파일 실종 문제입니다.
  • 표기된 해당 하위 경로(models/checkpoints/ 등)에 모델 원본 safetensors를 채워 넣으십시오.
  • ComfyUI에 모델 설치하기을 참고하세요. 이 장애에 대고 pip install을 절대 가동하지 마십시오.
• 에러 로그에 Python 라이브러리 예외 함수가 찍힘 → 파이썬 가상환경 라이브러리 간의 정합성 충돌입니다.
  • pip show <패키지명>을 쳐서 중복 설치 여부를 대조하십시오.

단계 5: 로그는 "Starting server"에서 멈추고 화면은 하얗게 나옴

콘솔에는 서버 실행 및 http://127.0.0.1:8188 수신 상태가 확인되는데 브라우저는 무한 로딩 중인 현상.

ComfyUI 코어는 켜진 상태입니다. 단지 켜지자마자 웹 화면을 로드하는 과정에서 일부 플러그인이 통신 지연을 야기하며 프론트엔드를 얼려 버린 상태입니다.

주요 원인 및 해결 요령:

• ComfyUI-Manager의 원격 동기화 지연: GitHub raw 서버 차단 등으로 타임아웃 지연이 생깁니다.
  • 조치: config.ini 파일을 열어 network_mode = offline 옵션으로 오프라인 기동 유도.
• BizyAir의 클라우드 API 동기화 재시도 루프: 키가 없거나 외부 통신 차단으로 백그라운드가 멎어 있는 상태입니다.
  • 조치: 실행 셸 환경변수 옵션에 BIZYAIR_SKIP_TRD_MODEL_CACHE=1을 할당하고 시작.

관련 가이드

• 워크플로 환경 구성
• 의존성 충돌
• 자주 발생하는 문제
• GPU 호환성