> ## Documentation Index > Fetch the complete documentation index at: https://dripart-mintlify-b90d3c69.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # ComfyUI 문제 해결 및 해결 방법 > 일반적인 ComfyUI 문제, 해결 방법 및 버그를 효과적으로 보고하는 방법 우리는 많은 피드백 이슈를 받고 있으며, 제출된 대부분의 이슈가 커스텀 노드와 관련되어 있음을 발견했습니다. 따라서 오류 보고서를 제출하기 전에 [커스텀 노드 문제 해결 가이드](/ko/troubleshooting/custom-node-issues)를 반드시 읽어보시기 바랍니다. 이렇게 하면 문제가 ComfyUI 핵심 문제로 인한 것이 아닌지 확인할 수 있습니다. 커스텀 노드로 인한 문제를 어떻게 해결하는지 확인하세요. ## 일반적인 문제 및 빠른 해결 방법 자세한 문제 해결에 들어가기 전에 다음의 일반적인 해결 방법을 시도해 보세요: ### ComfyUI가 시작되지 않음 **증상:** 애플리케이션이 시작 시 충돌하거나, 검은 화면이 나타나거나, 로딩에 실패함 **빠른 해결 방법:** 1. **시스템 요구 사항 확인** - 시스템이 [최소 요구 사항](/ko/installation/system_requirements)을 충족하는지 확인하세요. 2. **GPU 드라이버 업데이트** - NVIDIA/AMD/Intel에서 최신 드라이버를 다운로드하세요. ### 생성이 실패하거나 오류 발생 **증상:** "프롬프트 실행 실패" 대화상자에 "보고서 표시" 버튼이 있고, 워크플로우가 중단됨 **빠른 해결 방법:** 1. **"보고서 표시" 클릭** - 자세한 오류 메시지를 읽어 특정 문제를 파악하세요. 2. **커스텀 노드 문제인지 확인** - [커스텀 노드 문제 해결 가이드](/ko/troubleshooting/custom-node-issues)를 따르세요. 3. **모델 파일 확인** - 모델 설정은 [모델 문서](/ko/development/core-concepts/models)를 참조하세요. 4. **VRAM 사용량 확인** - GPU 메모리를 사용하는 다른 애플리케이션을 종료하세요. ### 성능 저하 **증상:** 생성 속도가 매우 느리거나, 시스템이 멈추거나, 메모리 부족 오류 발생 **빠른 해결 방법:** 1. **해상도/배치 크기 줄이기** - 이미지 크기나 이미지 수를 줄이세요. 2. **메모리 최적화 플래그 사용** - 아래의 성능 최적화 섹션을 참고하세요. 3. **불필요한 애플리케이션 종료** - RAM과 VRAM을 확보하세요. 4. **CPU/GPU 사용량 확인** - 작업 관리자를 이용해 병목 현상을 파악하세요. **성능 최적화 명령어:** 낮은 VRAM 시스템용: ```bash theme={null} # 낮은 VRAM 모드 (텍스트 인코더는 CPU 사용) python main.py --lowvram # CPU 모드 (매우 느리지만 모든 하드웨어에서 작동, 절대 마지막 수단으로만 사용) python main.py --cpu ``` 더 나은 성능을 위해: ```bash theme={null} # 미리보기 비활성화 (VRAM 및 처리 시간 절약) python main.py --preview-method none # 최적화된 주의 메커니즘 사용 python main.py --use-pytorch-cross-attention python main.py --use-flash-attention # 비동기 웨이트 오프로드 python main.py --async-offload ``` 메모리 관리를 위해: ```bash theme={null} # OS용 특정 VRAM 양 예약 (GB 단위) python main.py --reserve-vram 2 # 스마트 메모리 관리 비활성화 python main.py --disable-smart-memory # 다른 캐싱 전략 사용 python main.py --cache-none # RAM 사용량 적으나 속도 느림 python main.py --cache-lru 10 # 결과 10개 캐싱, 속도 빠름 python main.py --cache-classic # 구식(공격적) 캐싱 사용 ``` ## 설치별 문제 ### 데스크탑 앱 문제 종합적인 데스크탑 설치 문제 해결은 [데스크탑 설치 가이드](/ko/installation/desktop/windows)를 참조하세요. * **지원되지 않는 장치**: Comfy 데스크탑 Windows는 CUDA 지원 NVIDIA GPU만 지원합니다. 다른 GPU는 [ComfyUI 포터블](/ko/installation/comfyui_portable_windows) 또는 [수동 설치](/ko/installation/manual_install)를 사용하세요. * **설치 실패**: 설치 프로그램을 관리자 권한으로 실행하고, 최소 15GB 디스크 공간을 확보하세요. * **유지관리 페이지**: 다운로드가 실패하면 [미러 설정](/ko/installation/desktop/windows#mirror-settings)을 확인하세요. * **모델 누락**: 모델은 마이그레이션 시 복사되지 않고 링크만 생성됩니다. 모델 경로를 확인하세요. * **"앱이 손상되었습니다"**: 보안 및 개인정보 설정에서 앱 허용하세요. * **성능 문제**: 개인정보 설정에서 전체 디스크 접근 권한을 부여하세요. * **충돌**: Console 앱에서 충돌 보고서를 확인하세요. * **누락된 라이브러리**: 패키지 관리자로 의존성을 설치하세요. * **LD\_LIBRARY\_PATH 오류**: PyTorch 라이브러리 경로 문제 (아래 참조). ### 수동 설치 문제 문서 내용이 약간 오래되었을 수 있습니다. 문제가 발생하면 pytorch의 최신 안정 버전이나 나열된 라이브러리 중 하나가 있는지 수동으로 확인해 주세요. [pytorch 설치 매트릭스](https://pytorch.org/get-started/locally/)나 [ROCm 웹사이트](https://rocm.docs.amd.com/projects/install-on-linux/en/develop/install/3rd-party/pytorch-install.html#using-a-wheels-package)를 참고하세요. **파이썬 버전 충돌:** ```bash theme={null} # 파이썬 버전 확인 (3.9+ 필요, 3.12 권장) python --version # 가상환경 사용 (권장) python -m venv comfyui_env source comfyui_env/bin/activate # Linux/Mac comfyui_env\Scripts\activate # Windows ``` **패키지 설치 실패:** ```bash theme={null} # 먼저 pip 업데이트 python -m pip install --upgrade pip # 의존성 설치 pip install -r requirements.txt # NVIDIA GPU용 (CUDA 13.0) pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130 # AMD GPU용 (Linux만 - ROCm 7.2) pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2 ``` ### Linux 특수 문제 **LD\_LIBRARY\_PATH 오류:** 일반적인 증상: * "libcuda.so.1: 공유 객체 파일을 열 수 없음" * "libnccl.so: 공유 객체 파일을 열 수 없음" * "ImportError: libnvinfer.so.X: 공유 객체 파일을 열 수 없음" **해결 방법:** 1. **현대적 PyTorch 설치 (가장 일반적):** ```bash theme={null} # NVIDIA 패키지가 포함된 가상환경용 export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH # conda 환경용 export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH # 또는 자동으로 파이썬 site-packages 찾기 PYTHON_PATH=$(python -c "import site; print(site.getsitepackages()[0])") export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH # 추가로 NVIDIA 라이브러리 필요할 수도 있음 export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cuda_runtime/lib:$LD_LIBRARY_PATH export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cublas/lib:$LD_LIBRARY_PATH ``` 2. **사용 가능한 라이브러리 확인:** ```bash theme={null} # 설치된 NVIDIA 패키지 확인 python -c "import site; import os; nvidia_path=os.path.join(site.getsitepackages()[0], 'nvidia'); print('NVIDIA libs:', [d for d in os.listdir(nvidia_path) if os.path.isdir(os.path.join(nvidia_path, d))] if os.path.exists(nvidia_path) else 'Not found')" # PyTorch가 필요한 누락된 라이브러리 찾기 python -c "import torch; print(torch.__file__)" ldd $(python -c "import torch; print(torch.__file__.replace('__init__.py', 'lib/libtorch_cuda.so'))") ``` 3. **환경에 영구적으로 설정:** ```bash theme={null} # 가상환경에서는 활성화 스크립트에 추가 echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> $VIRTUAL_ENV/bin/activate # conda 환경 conda env config vars set LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH # 글로벌 bashrc에 추가 (파이썬 버전 조정 필요) echo 'export LD_LIBRARY_PATH=$(python -c "import site; print(site.getsitepackages()[0])")/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> ~/.bashrc ``` 4. **대체 방법: ldconfig 사용:** ```bash theme={null} # 현재 라이브러리 캐시 확인 ldconfig -p | grep cuda ldconfig -p | grep nccl # 없으면 라이브러리 경로 추가 (root 권한 필요) sudo echo "/usr/local/cuda/lib64" > /etc/ld.so.conf.d/cuda.conf sudo ldconfig ``` 5. **라이브러리 로딩 디버깅:** ```bash theme={null} # 상세한 라이브러리 로딩 확인 LD_DEBUG=libs python main.py 2>&1 | grep "looking for" # PyTorch CUDA 사용 가능 여부 확인 python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)" ``` ## 모델 관련 문제 아키텍처 불일치, 모델 누락, 로딩 오류 등 종합적인 모델 문제 해결은 전용 [모델 문제](/ko/troubleshooting/model-issues) 페이지를 참조하세요. ## 네트워크 및 API 문제 ### 파트너 노드 작동하지 않음 **증상:** API 호출 실패, 타임아웃 오류, 할당량 초과 **해결 방법:** 1. **API 키 유효성 확인** - [사용자 설정](/ko/interface/user)에서 키를 확인하세요. 2. **계정 크레딧 확인** - 충분한 [API 크레딧](/ko/interface/credits)이 있는지 확인하세요. 3. **인터넷 연결 확인** - 다른 온라인 서비스로 테스트하세요. 4. **서비스 상태 확인** - 제공자가 다운타임을 겪고 있을 수 있습니다. ### 연결 문제 **증상:** "서버에 연결할 수 없음", 타임아웃 오류 **해결 방법:** 1. **방화벽 설정 확인** - ComfyUI를 방화벽에 허용하세요. 2. **다른 포트 사용** - 기본은 8188이며, 8189 또는 8190을 시도해 보세요. 3. **VPN 일시 비활성화** - VPN이 연결을 차단하고 있을 수 있습니다. 4. **프록시 설정 확인** - 필요하지 않은 경우 프록시를 비활성화하세요. ### 프론트엔드 문제 **"프론트엔드 또는 템플릿 패키지가 업데이트되지 않았습니다":** ```bash theme={null} # Git을 통해 ComfyUI 업데이트 후 프론트엔드 의존성 업데이트 pip install -r requirements.txt ``` **"커스텀 노드를 찾을 수 없습니다":** * ComfyUI 설정에서 노드 검증을 비활성화하세요. **"워크플로우 검증 실패에 대한 오류 알림":** * 설정에서 워크플로우 검증을 일시적으로 비활성화하세요. * ComfyUI 팀에 문제를 보고하세요. **로컬호스트가 아닌 경우 로그인 문제:** * 정상적인 로그인은 로컬호스트에서만 가능합니다. * LAN/원격 접속을 위해서는 [platform.comfy.org/login](https://platform.comfy.org/login)에서 API 키를 생성하세요. * 로그인 대화상자나 `--api-key` 명령줄 인수로 API 키를 사용하세요. ## 하드웨어별 문제 ### NVIDIA GPU 문제 **"Torch가 CUDA 지원으로 컴파일되지 않았습니다" 오류:** ```bash theme={null} # 먼저 torch 제거 pip uninstall torch # CUDA 13.0 지원 안정 버전 PyTorch 설치 pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130 # Nightly 빌드 (성능 개선 가능) pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132 # CUDA 지원 확인 python -c "import torch; print(torch.cuda.is_available())" ``` **GPU가 감지되지 않음:** ```bash theme={null} # GPU가 보이는지 확인 nvidia-smi # 드라이버 버전 및 CUDA 호환성 확인 nvidia-smi --query-gpu=driver_version --format=csv ``` ### AMD GPU 문제 **ROCm 지원 (Linux만):** ```bash theme={null} # 안정 버전 ROCm PyTorch 설치 (작성 당시 7.2) pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2 # Nightly 빌드 (ROCm 7.2 작성 당시, 성능 개선 가능) pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm7.2 ``` **지원되지 않는 AMD GPU:** ```bash theme={null} # RDNA2 이하 (6700, 6600) HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py # RDNA3 카드 (7600) HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py ``` **성능 최적화:** ```bash theme={null} # 실험적 메모리 효율적 주의 활성화 (PyTorch 2.4 이후 더 이상 필요 없음) TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention # 조정 가능한 연산 활성화 (첫 실행은 느리지만 이후는 빠릅니다) PYTORCH_TUNABLEOP_ENABLED=1 python main.py ``` ### Apple Silicon (M1/M2/M3) 문제 **MPS 백엔드 설정:** ```bash theme={null} # Apple Silicon용 PyTorch Nightly 설치 # Apple 가이드 참고: https://developer.apple.com/metal/pytorch/ # MPS 사용 가능 여부 확인 python -c "import torch; print(torch.backends.mps.is_available())" # ComfyUI 실행 python main.py ``` **MPS로 인해 문제가 발생할 경우:** ```bash theme={null} # 강제로 CPU 모드 사용 python main.py --cpu # 메모리 최적화와 함께 python main.py --force-fp16 --cpu ``` ### Intel GPU 문제 **옵션 1: 기본 PyTorch XPU 지원 (Windows/Linux):** ```bash theme={null} # XPU 지원 PyTorch Nightly 설치 pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu # ComfyUI 실행 python main.py ``` **옵션 2: Intel Extension for PyTorch (IPEX):** ```bash theme={null} # Intel Arc A-Series 그래픽용 conda install libuv pip install torch==2.3.1.post0+cxx11.abi torchvision==0.18.1.post0+cxx11.abi torchaudio==2.3.1.post0+cxx11.abi intel-extension-for-pytorch==2.3.110.post0+xpu --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/ ``` ## 도움 요청 및 버그 보고 ### 버그 보고 전 1. **알려진 문제인지 확인:** * [GitHub 이슈](https://github.com/Comfy-Org/ComfyUI/issues) 검색 * [ComfyUI 포럼](https://forum.comfy.org/) 확인 * [Discord 토론](https://discord.com/invite/comfyorg) 검토 2. **기본 문제 해결 시도:** * [기본 워크플로우](/ko/get_started/first_generation)로 테스트 * 모든 커스텀 노드 비활성화 (커스텀 노드 문제 해결 참고) * 콘솔/터미널에서 오류 메시지를 확인 * comfy-cli 사용 시 `comfy node update all`로 업데이트 시도 ### 효과적인 버그 보고 방법 #### ComfyUI 핵심 문제 **보내는 곳:** [GitHub 이슈](https://github.com/Comfy-Org/ComfyUI/issues) #### 데스크탑 앱 문제 **보내는 곳:** [데스크탑 GitHub 이슈](https://github.com/Comfy-Org/desktop/issues) #### 프론트엔드 문제 **보내는 곳:** [프론트엔드 GitHub 이슈](https://github.com/Comfy-Org/ComfyUI_frontend/issues) #### 커스텀 노드 문제 **보내는 곳:** 특정 커스텀 노드 개발자에게 문의 ### 필수 정보 어떤 문제든 보고할 때 다음 정보를 포함하세요: **시스템 정보 (설정의 정보 페이지에서 확인 가능):** * 운영체제 (Windows 11, macOS 14.1, Ubuntu 22.04 등) * ComfyUI 버전 (설정의 정보 페이지 확인) * 파이썬 버전: `python --version` * PyTorch 버전: `python -c "import torch; print(torch.__version__)"` * GPU 모델 및 드라이버 버전 * 설치 방법 (데스크탑, 포터블, 수동, comfy-cli) 설정의 정보 페이지 ```bash theme={null} # 시스템 정보 systeminfo | findstr /C:"OS Name" /C:"OS Version" # GPU 정보 wmic path win32_VideoController get name # 파이썬 & PyTorch 정보 python --version python -c "import torch; print(f'PyTorch: {torch.__version__}')" python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')" ``` ```bash theme={null} # 시스템 정보 uname -a # GPU 정보 (Linux) lspci | grep VGA # 파이썬 & PyTorch 정보 python --version python -c "import torch; print(f'PyTorch: {torch.__version__}')" python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')" ``` **데스크탑 앱 문제의 경우 다음도 포함하세요:** * 로그 파일: `C:\Users\\AppData\Roaming\ComfyUI\logs` (Windows) * 설정 파일: `C:\Users\\AppData\Roaming\ComfyUI` (Windows) **문제 상세 정보:** * 문제에 대한 명확한 설명 * 문제 재현 단계 * 예상 행동과 실제 행동 비교 * 해당되는 경우 스크린샷 또는 동영상 **오류 메시지:** * 콘솔/터미널의 전체 오류 텍스트 * 브라우저 콘솔 오류 (F12 → 콘솔 탭) * 충돌 로그 또는 오류 대화상자 **추가 상황:** * 설치된 커스텀 노드 목록 * 문제를 재현하는 워크플로우 파일 (.json) * 최근 변경사항 (새로운 설치, 업데이트 등) ## 커뮤니티 리소스 * **공식 포럼:** [forum.comfy.org](https://forum.comfy.org/) * **Discord:** [ComfyUI Discord 서버](https://discord.com/invite/comfyorg) * **Reddit:** [r/comfyui](https://reddit.com/r/comfyui) * **YouTube:** [ComfyUI 튜토리얼](https://www.youtube.com/@comfyorg)