블루투스를 쓰지 않는 PC에서도 에이전트 설치가 실행 코드 오류로 막힌 경우

블루투스 기능을 켜지도 않았는데, bthprops.cpl 파일이 없는 PC에서는 에이전트 설치·실행 자체가 막혔다. 원인은 블루투스 API DLL을 정적 임포트해 둔 한 줄이었다. 동적 로드로 바꾸고 15대 운영 환경과 VM 시험으로 회귀 여부까지 확인한 과정을 정리한다.

증상

한 고객사 PC에 에이전트를 설치하는 중 이런 창이 떴다.

bthprops.cpl이(가) 없어 코드 실행을 진행할 수 없습니다.

인스톨러도 끝까지 가지 못하고 이렇게 멈췄다.

설치를 완료하지 못했습니다. (코드 -1073741515)
디스크 상태를 확인한 뒤 다시 설치하십시오.

orange.exe --remove, orange.exe --install 둘 다 같은 창이 떴다. 디스크 문제가 아니었다. 이 PC에는 블루투스 어댑터가 없었고, 당연히 bthprops.cpl(블루투스 API DLL)도 없었다.

원인 — 정적 임포트 한 줄

orange.exe가 bthprops.cpl을 정적으로 임포트하고 있었다. Plugin\Hardware\CHardwarePlugin.BLUETOOTH.cpp:15의 #pragma comment(lib, "Bthprops.lib") 한 줄이 원인이었고, 2026-09-05 커밋(d1b42483)부터 들어가 있었다.

정적 임포트는 프로세스가 뜨는 순간 Windows 로더가 임포트 테이블에 적힌 DLL을 전부 찾아 로드한다. 파일이 없으면 코드 한 줄도 실행되기 전에 0xC0000135(STATUS_DLL_NOT_FOUND)로 프로세스 시작 자체가 막힌다. 블루투스 기능을 쓰는지 여부와는 무관하다 — 블루투스 화면을 한 번도 열지 않았어도, bthprops.cpl이 없으면 orange.exe 자체가 뜨지 않는다.

영향 범위는 orange.exe 하나였다. 같은 패키지의 orange.user.exe, orange.analyst.exe에는 이 임포트가 없었다.

수정 — 동적 로드로 전환

LoadLibraryExW(L"bthprops.cpl", NULL, LOAD_LIBRARY_SEARCH_SYSTEM32)와 GetProcAddress로 필요한 블루투스 API 7종을 실행 중에 직접 찾아 쓰도록 바꿨다. 로드에 실패하면 해당 PC는 블루투스 관련 항목을 전부 "지원 안 함"으로 응답하고, 나머지 기능은 그대로 동작한다.

구조는 파일 static 함수 모음이 아니라 클래스로 다시 짰다. 신규 Plugin\Hardware\CBluetooth.h에 CBluetoothApi(생성자에서 LoadLibraryExW, 소멸자에서 FreeLibrary, 함수 7개 래퍼)와 이를 상속하는 CBluetooth(기존 파일 static 함수 14개를 멤버로 이동)를 두고, CHardwarePlugin이 CBluetooth 멤버를 하나 들고 있는 모양이다. Bthprops.lib 링크는 제거했고, 호출하는 곳이 없던 Discovery 계열 API 2개도 함께 정리했다. 6개 파일, +247/−85.

로드 실패는 최초 1회만 시도하고 에이전트가 다시 시작되기 전까지는 재시도하지 않는다. 파일이 없는 PC에서 매번 다시 찾는 비용을 피하기 위한 결정이다.

검증

코드 수준

독립 테스트 exe로 임포트 테이블을 비교했다. 수정 전 exe는 bthprops.cpl이 임포트 목록에 있었고, 수정 후에는 없었다(dumpbin /dependents 44개 → 43개, 차이는 정확히 bthprops.cpl 하나). 파일이 있는 PC에서 동적 로드로 호출한 값과 원본 정적 임포트로 호출한 값(BtPairedSEH, BtRadioSEH 등)이 같았고, DLL 이름이나 함수 이름을 일부러 틀리게 바꾼 변형에서는 의도한 대로 실패 값이 나왔다.

리뷰는 3회(정확성·동등성·Codex 교차검증) 진행했고 결함은 남지 않았다. 리뷰 중 나온 지적 — 파일이 없는 PC를 블루투스 스택 자체의 장애로 잘못 알릴 수 있는 조건, DLL 초기화 중 예외가 나는 경우 등 — 은 코드에 반영했다.

VM 시험 — 파일 있음/없음 비교

블루투스 어댑터가 없는 VM(Windows 10 19045)에서 운영 중인 에이전트를 대상으로 bthprops.cpl의 이름을 바꿔 파일이 "없는" 상태를 만들고 서비스 재시작과 설치 파일(ORANGE.x64.exe /S) 재설치를 각각 시험했다.

단계bthprops.cpl결과
변경 전있음정상 기동, 기준값
이름 바꿈 → 서비스 재시작없음정상 기동(Running), 오류 이벤트 없음
파일 없는 채로 재설치없음설치기 종료 코드 0, 서비스 Running
이름 복구 → 재시작있음정상 기동, 실행 중 bthprops.cpl 로드 확인

네 단계 모두 블루투스 상태 응답 8줄(bt_device_power, bt_connectable, bt_service, bt_usb_suspend, bt_hub_power, bt_fast_startup, bt_adapter, bt_paired)이 동일했다. 파일이 없어도 설치·기동 창이나 0xC0000135 오류는 나타나지 않았다.

이 VM에는 블루투스 어댑터 자체가 없어서 "파일이 없을 때 블루투스 관련 항목만 지원 안 함으로 바뀐다"는 변화는 이 VM에서는 구분되지 않았다. 이 부분은 별도로 블루투스 어댑터가 있는 PC(대표 PC)에서 파일 유무를 직접 비교해 확인했다.

운영 환경 확인

이 버전을 배포한 뒤 온라인 15대가 모두 크래시·롤백·비정상종료 없이 올라왔다. 블루투스 어댑터 종류가 다른 PC 여럿에서 응답을 비교했는데, 그중 QCA9377 블루투스 4.1 어댑터가 달린 한 PC에서 bt_device_power 항목만 "지원 안 함"으로 나오는 경우가 있었다. 이번 수정 범위에 있는 함수(전원 관리 조회)가 이름만 바뀐 것이라 수정으로 인한 회귀는 아니었고, WMI로 해당 장치의 전원 관리 노출 여부를 조회해 보니 드라이버 자체가 전원 관리를 노출하지 않는 장치였다. 장치 관리자에도 전원 관리 탭이 없는 것과 같은 경우로, "지원 안 함" 응답이 맞는 판정이었다.

Windows Server 2016 환경에서도 같은 버전으로 자동 업데이트가 정상적으로 이뤄졌고, 블루투스 상태 응답에 변화가 없었다.

마무리

이 건은 처음 제보된 고객사 PC의 Windows 버전과 bthprops.cpl 파일 유무를 직접 확인하지 못한 상태에서 수정이 이뤄졌다. 하지만 동적 로드로 바꾼 뒤부터는 파일 유무와 무관하게 orange.exe가 정상적으로 뜨고 블루투스 항목만 "지원 안 함"으로 응답하므로, 확인 결과에 따라 코드를 바꿀 필요가 없어졌다. 이후 배포 버전이 해당 PC에 반영되면 설치 성공 여부만 다시 확인하면 되는 상태로 마무리했다.


Orange Platform의 Windows 에이전트 설치 오류 진단 사례 정리입니다.