UniFi 컨트롤러 소프트웨어를 실행할 때 '시작 실패(startup failed)' 오류 메시지가 나타나는 주요 원인은 시스템 드라이브의 여유 공간 부족입니다. 또한 손상되었거나 구버전으로 설치된 Java 또는 UniFi 컨트롤러 소프트웨어 자체도 이 오류의 원인이 될 수 있습니다.
이 오류는 사용자가 UniFi 컨트롤러 소프트웨어를 실행하려고 할 때 발생합니다. 경우에 따라서는 컨트롤러 소프트웨어를 업그레이드한 직후에 오류가 나타나기도 하며, 어떤 사용자들은 애플리케이션 실행 후 5분 이상 지나서야 오류 메시지를 확인하기도 했습니다. 이 문제는 Windows, Linux, Mac, 라즈베리 파이(Raspberry Pi) 사용자들 모두에게 보고되고 있습니다.
문제 해결을 시작하기 전에 먼저 네트워크 유형이 개인(Private) 또는 도메인(Domain)으로 설정되어 있는지 확인하세요.
해결 방법 1: 작업 관리자에서 UniFi 관련 프로세스 종료하기
일시적인 소프트웨어 또는 통신 오류로 인해 문제가 발생했을 수 있습니다. 이 경우 UniFi와 관련된 모든 프로세스를 종료한 후 소프트웨어를 다시 실행하면 문제가 해결될 수 있습니다. 여기서는 Windows PC 기준으로 설명합니다.
- UniFi 컨트롤러 애플리케이션을 종료합니다.
- Windows 버튼을 마우스 오른쪽 버튼으로 클릭하고 표시되는 메뉴에서 작업 관리자(Task Manager)를 클릭합니다.
- 프로세스 탭에서 UniFi 컨트롤러 소프트웨어에 해당하는 프로세스를 선택한 후 작업 끝내기 버튼을 클릭합니다. UniFi 컨트롤러에 속한 모든 프로세스에 대해 반복합니다.
- 이후 Java 및 MongoD와 관련된 모든 프로세스도 종료합니다.
- 컨트롤러 소프트웨어를 다시 실행하여 정상적으로 작동하는지 확인합니다. 의존성을 다시 구축하는 과정이 필요하므로 로딩에 시간이 걸릴 수 있습니다.
해결 방법 2: 시스템 드라이브의 여유 공간 확보하기
UniFi 컨트롤러 소프트웨어가 정상적으로 작동하려면 시스템 드라이브에 일정량의 추가 여유 공간이 필요합니다. 시스템 드라이브에 충분한 여유 공간이 없다면 이 오류가 발생할 수 있습니다. 이 경우 시스템 드라이브(C 드라이브)의 공간을 확보하면 문제가 해결될 수 있습니다.
- C 드라이브(시스템 드라이브)의 여유 공간을 확보합니다.
- 그런 다음 컨트롤러 애플리케이션을 실행하여 정상 작동 여부를 확인합니다.
해결 방법 3: System.Properties 파일에서 스토리지 엔진 변경하기
데이터베이스가 'mmapv1' 스토리지 엔진으로 생성되었는데 설정 파일에는 'wiredTiger' 스토리지 엔진이 지정되어 있다면 이 오류가 발생할 수 있습니다. 이 경우 컨트롤러 애플리케이션이 mmapv1 스토리지 엔진을 사용하도록 강제하면 문제가 해결될 수 있습니다. Windows PC 기준으로 설명합니다.
- 파일 탐색기를 열고 컨트롤러 애플리케이션의 설치 디렉터리로 이동합니다. 일반적으로 다음 경로입니다.
%USERPROFILE%\Ubiquiti UniFi\data
- System.properties 파일을 메모장으로 연 후 파일 맨 끝에 다음 줄을 추가합니다.
db.extraargs=--storageEngine=mmapv1
- 변경 사항을 저장하고 메모장을 종료합니다.
- 컨트롤러 애플리케이션을 실행하여 정상 작동하는지 확인합니다.
해결 방법 4: 특수 문자가 없는 사용자 프로필 사용하기
사용자 프로필 이름에 특수 문자가 포함되어 있으면 Ubiquiti UniFi 폴더 경로에도 특수 문자가 포함되게 되며(예: C:\Users\ÄçìÞôñçò\Ubiquiti UniFi), UniFi 컨트롤러는 이런 경로에서 알려진 문제를 일으킵니다. 이 경우 특수 문자가 없는 새 사용자 프로필을 만들면 문제가 해결될 수 있습니다. 참고로 현재 사용자 이름만 변경해서는 Ubiquiti UniFi 폴더 경로에 반영되지 않으므로, 새 사용자 계정을 생성하고 모든 데이터를 그 계정으로 옮겨야 합니다.
- Windows PC에 새 사용자 계정을 만들고 기존 데이터를 모두 옮깁니다.
- 그런 다음 컨트롤러 소프트웨어에서 오류가 사라졌는지 확인합니다.
해결 방법 5: UniFi 컨트롤러가 요구하는 기본 포트 비우기
UniFi 컨트롤러 애플리케이션은 정상 작동을 위해 기본적으로 8080 포트가 필요합니다. 해당 포트를 다른 프로그램이 이미 사용 중이라면 이 오류가 발생할 수 있습니다. 이 경우 해당 포트를 사용 중인 프로그램을 중지하거나, 문제가 되는 프로그램(또는 UniFi 컨트롤러)이 다른 포트를 사용하도록 설정하면 해결될 수 있습니다.
- Windows PC를 클린 부팅한 후 문제가 해결되는지 확인합니다.
- 문제가 해결되었다면 포트 충돌을 일으키는 프로그램을 찾아냅니다. 또는 UniFi 컨트롤러의 기본 포트를 다른 값으로 변경할 수도 있습니다.
해결 방법 6: UniFi 로그 파일 이름 변경하기
UniFi 컨트롤러는 다른 많은 애플리케이션과 마찬가지로 문제 해결을 돕기 위해 로그를 생성합니다. 이 로그 파일이 손상되면 해당 오류가 발생할 수 있습니다. 이 경우 로그 파일의 이름을 변경하면(다음 실행 시 새 로그 파일이 생성됨) 문제가 해결될 수 있습니다. Windows 기준으로 설명합니다.
- UniFi 컨트롤러 애플리케이션을 종료하고 작업 관리자를 통해 관련된 모든 프로세스를 종료합니다(해결 방법 1 참조).
- 파일 탐색기를 열고 설치 디렉터리로 이동합니다. 일반적으로 다음 경로입니다.
%USERPROFILE%\Ubiquiti UniFi\logs\
- 로그 파일의 이름을 변경합니다. mongod 로그와 server 로그의 이름도 변경하는 것을 잊지 마세요(파일 확장자 뒤에 .old를 추가). 그런 다음 소프트웨어를 실행하여 문제가 해결되었는지 확인합니다.
해결 방법 7: UniFi 폴더 내 저널(Journal) 파일 삭제하기
UniFi 컨트롤러 소프트웨어는 저널(journal) 파일을 사용해 다양한 종류의 데이터를 저장합니다. 이 저널 파일이 손상되면 해당 오류가 발생할 수 있습니다. 이 경우 저널 파일을 삭제하면 문제가 해결될 수 있습니다. Windows PC 기준으로 설명합니다.
- UniFi 컨트롤러 소프트웨어를 종료하고 작업 관리자를 통해 실행 중인 모든 프로세스를 종료합니다(해결 방법 1 참조).
- 파일 탐색기를 열고 애플리케이션의 설치 디렉터리로 이동합니다. 일반적으로 다음 경로입니다.
%USERPROFILE%\Ubiquiti UniFi\data\db\journal
- 만약을 대비해 폴더 내 모든 파일을 안전한 위치에 백업합니다.
- 이제 폴더 안의 모든 파일을 삭제하고 시스템을 재시작합니다.
- 재시작 후 컨트롤러 애플리케이션을 실행하여 정상 작동하는지 확인합니다.
해결 방법 8: UniFi 컨트롤러를 서비스로 설치하기
UniFi 컨트롤러 소프트웨어가 서비스로 설치되어 있지 않으면 다양한 문제가 발생할 수 있으며, 현재 오류의 원인이 될 수도 있습니다. 이 경우 컨트롤러 소프트웨어를 서비스로 설치하면 문제가 해결될 수 있습니다.
- 컨트롤러를 종료하고 작업 관리자를 통해 실행 중인 모든 프로세스를 닫습니다(해결 방법 1 참조).
- 시스템 환경 변수에 Java 경로를 추가합니다(Temp 변수의 경로 맨 끝에 추가). 일반적으로 다음과 같습니다.
C:\Program Files(x86)\Java\jre7\bin\javaw.exe
- 작업 표시줄의 Windows 검색 상자를 클릭하고 명령 프롬프트를 입력합니다. 검색 결과 목록에서 명령 프롬프트를 마우스 오른쪽 버튼으로 클릭하고 관리자 권한으로 실행을 선택합니다.
- 다음 명령어를 입력하고 Enter 키를 누릅니다.
cd "%UserProfile%\Ubiquiti UniFi\"
- UniFi 디렉터리에서 다음 명령어를 입력하고 Enter 키를 누릅니다.
java -jar lib\ace.jar installsvc
- 'Complete Installation'이라는 메시지가 표시되면 다음 명령어를 입력하고 Enter 키를 누릅니다.
java -jar lib\ace.jar startsvc
- 이후 명령 프롬프트를 종료합니다.
- 'UniFi' 서비스가 실행 중인지 확인하려면 작업 관리자를 열고 서비스 탭에서 UniFi 서비스를 확인합니다.
- 이제 컨트롤러의 인터페이스 IP에 접속하여 문제가 해결되었는지 확인합니다.
해결 방법 9: Java를 최신 빌드로 업데이트하기
Java는 UniFi 컨트롤러 소프트웨어 작동에 필수적입니다. Java는 새로운 기술 발전에 대응하고 알려진 버그를 수정하기 위해 정기적으로 업데이트됩니다. 구버전의 Java를 사용 중이라면 이 오류가 발생할 수 있습니다. 이 경우 Java를 최신 빌드로 업데이트하면 문제가 해결될 수 있습니다. Windows PC 기준으로 설명합니다.
- 작업 표시줄의 Windows 검색 상자를 클릭하고 Java를 입력합니다. 결과 목록에서 Configure Java를 클릭합니다.
- Update 탭을 클릭한 후 창 우측 하단에 있는 지금 업데이트(Update Now) 버튼을 클릭합니다.
- Java 업데이트 후 UniFi 컨트롤러 소프트웨어에서 오류가 사라졌는지 확인합니다.
해결 방법 10: Java 재설치하기
Java 업데이트로 문제가 해결되지 않았다면 손상된 Java 설치 또는 호환되지 않는 Java 버전이 원인일 수 있습니다. 이 경우 Java를 제거한 후 다시 설치하면 문제가 해결될 수 있습니다. Windows 기준으로 설명합니다.
- UniFi 컨트롤러 소프트웨어를 종료하고 작업 관리자를 통해 관련된 모든 프로세스를 종료합니다(해결 방법 1 참조).
- 애플리케이션이 서비스로 설치되어 있다면 해당 서비스를 제거(uninstall)합니다.
- 작업 표시줄의 Windows 검색 상자를 클릭하고 제어판을 입력합니다. 결과 목록에서 제어판을 클릭합니다.
- 프로그램 제거를 클릭합니다.
- Java를 마우스 오른쪽 버튼으로 클릭하고 제거를 선택합니다. 화면의 안내에 따라 제거 과정을 완료합니다.
- 시스템을 재시작합니다. 단, 시스템 시작 시 컨트롤러 애플리케이션이 자동으로 실행되지 않도록 합니다.
- 이제 최신 버전의 Java를 다운로드하여 설치합니다(UniFi가 정상 작동하려면 Windows에는 64비트 버전의 Java를 설치해야 합니다). 방화벽에서 네트워크 통신을 위해 Java 허용 여부를 묻는 메시지가 나타나면 허용합니다.
- 컨트롤러 애플리케이션을 실행하여 오류가 사라졌는지 확인합니다.
해결 방법 11: UniFi Network Controller 소프트웨어 재설치하기
Java를 다시 설치해도 문제가 해결되지 않았다면 UniFi 컨트롤러 소프트웨어 자체의 손상 또는 구버전 설치가 원인일 가능성이 높습니다. 이 경우 컨트롤러 소프트웨어를 제거한 후 다시 설치하면 문제가 해결될 수 있습니다. Windows PC 기준으로 설명합니다.
- 컨트롤러 애플리케이션을 종료하고 작업 관리자를 통해 관련된 모든 프로세스를 종료합니다(해결 방법 1 참조).
- 파일 탐색기를 열고 다음 경로로 이동합니다.
%userprofile%\Ubiquiti UniFi\data\backup
- 설정 파일(.unf 파일)을 안전한 위치에 백업합니다.
- 작업 표시줄의 Windows 검색 상자를 클릭하고 제어판을 입력합니다. 검색 결과 목록에서 제어판을 클릭합니다.
- 프로그램 제거를 클릭합니다.
- 설치된 애플리케이션 목록에서 UniFi 컨트롤러 소프트웨어를 마우스 오른쪽 버튼으로 클릭하고 제거를 선택합니다. 설정을 유지할지 묻는 메시지가 나타나면 아니요(No)를 클릭합니다.
- 화면의 안내에 따라 제거 과정을 완료합니다.
- 파일 탐색기를 열고 다음 경로로 이동합니다.
%userprofile%\Ubiquiti UniFi
- 이 폴더를 완전히 삭제합니다.
- 해결 방법 10에서 설명한 대로 Java를 제거합니다.
- 최신 버전의 UniFi Network Controller 소프트웨어를 다운로드하여 설치합니다.
- 백업해 둔 .unf 파일(2~3단계에서 백업)로부터 설정을 복원합니다.
- 이제 UniFi Network Controller 소프트웨어를 실행합니다. 이제 오류 없이 정상적으로 작동할 것입니다.