게시글 상세
목록으로PlatformIO + VSCode 환경에서 발생한 Package Mirror 오류와 해결방법
조회수: 55
작성자: june9152
등록일: 2025-11-11 03:22
수정일: 2025-12-21 02:17
PlatformIO VSCode Contabo Mirror 오류 해결 가이드
PlatformIO를 VSCode에서 사용할 때 다음과 같은 오류 메시지가 발생할 수 있습니다.
Warning! Package Mirror: HTTPSConnectionPool(host='sin1.contabostorage.com', port=443): Max retries exceeded
이 문제는 PlatformIO가 필요한 패키지(예: tool-scons, toolchain 등)를 다운로드할 때 기본 미러 서버 sin1.contabostorage.com에 연결하지 못해 생기는 현상입니다.
1. 주요 원인
- Contabo 미러 서버 일시 중단 또는 응답 지연
- 방화벽, 네트워크 정책, SSL 인증서 문제
- 프록시 또는 DNS 설정 오류
2. 해결 절차
① 캐시 정리 및 업데이트
VSCode 명령 팔레트(Ctrl+Shift+P) → “PlatformIO: Open PlatformIO Core CLI” 선택 후 다음 명령을 입력하세요.
pio system prune --cache -f
pio upgrade
pio pkg update
pio platform update
만약
'pio' 용어가 인식되지 않습니다라는 메시지가 나오면,
%USERPROFILE%\.platformio\penv\Scripts\pio.exe를 직접 실행하거나
Python을 이용해 pip install -U platformio로 설치하세요.
② PowerShell에서 직접 실행
$pio = "$env:USERPROFILE\.platformio\penv\Scripts\pio.exe"
& $pio --version
& $pio system prune --cache -f
& $pio upgrade
& $pio pkg update
& $pio platform update
③ Core CLI가 없는 경우
VSCode의 PlatformIO 확장을 재설치하거나 Python으로 설치하세요:
py -m pip install -U platformio3. 미러 서버 우회 및 안정화
Contabo 미러 서버의 신뢰도가 낮은 경우, 공식 PyPI 또는 카카오 미러로 변경하면 속도와 안정성이 향상됩니다.
pip install 패키지명 -i https://mirror.kakao.com/pypi/simple
기업/기관망에서는 SSL 검사나 보안 장비가 contabostorage.com을 차단할 수 있으니
일시적으로 보안 소프트웨어를 비활성화하거나 허용 목록에 추가하세요.
4. 네트워크 점검
서버 연결 상태를 다음 명령으로 확인할 수 있습니다.
ping sin1.contabostorage.com
nslookup sin1.contabostorage.com
5. 결론
PlatformIO의 Contabo Mirror 오류는 일시적인 네트워크 문제로 인해 발생하는 경우가 많습니다.
CLI를 통한 캐시 정리와 업그레이드 절차를 거치면 대부분 해결됩니다.
VSCode 내부 CLI 또는 PowerShell에서 직접 pio.exe를 실행해 환경을 정리하면
ESP32, Python, 시놀로지 NAS 등 다양한 환경에서도 안정적으로 빌드가 가능합니다.
By J-IoT Technical Documentation | Last Updated: 2025-11-11