[rpi] Recalbox가 초기 로딩 후 종료된 원인: favoritesonly=1과 즐겨찾기 0개의 예외 처리 버그

Recalbox가 부팅 로고와 EmulationStation 초기 로딩까지는 정상적으로 진행되지만, 게임 목록을 읽은 직후 프런트엔드가 종료되는 문제가 발생했다. 저장장치 고장이나 ROM 손상을 먼저 의심하기 쉬운 증상이지만, 이번 사례의 직접 원인은 설정값 하나와 빈 즐겨찾기 목록의 조합이었다.

핵심만 요약하면 다음과 같다.

emulationstation.favoritesonly=1인 상태에서 즐겨찾기로 지정된 게임이 하나도 없으면 모든 시스템이 보이지 않게 된다. Recalbox 10.0.8의 EmulationStation은 이를 빈 검색 결과로 처리하지 않고 시스템 설정 파일을 불러오지 못한 것처럼 판단해 종료한다.

ROM을 삭제하거나 Recalbox를 다시 설치할 필요는 없다. recalbox.conf에서 emulationstation.favoritesonly를 0으로 되돌리면 되는 설정 문제다.

테스트 환경

• Recalbox 10.0.8
• Raspberry Pi Compute Module 4 Rev 1.1
• Raspberry Pi 4 계열 이미지
• USB 어댑터로 연결한 NVMe
• 내부 SHARE 파티션

다른 버전이나 하드웨어에서도 같은 코드 경로를 사용한다면 재현될 수 있지만, 이 글에서 직접 확인한 범위는 위 환경이다.

증상

부팅 자체는 성공했다. EmulationStation은 시스템과 게임 목록을 스캔했고, 로그에도 비가상 시스템 127개가 기록됐다. 그러나 스캔 직후 다음 오류를 출력하고 약 30초 뒤 정상 종료 절차를 밟았다.

[1980/01/01 02:00:56.443] (INFO ) : [System] Final non-virtual visible systems: 127
[1980/01/01 02:00:56.445] (INFO ) : [System] Gamelist load time: 4776ms
[1980/01/01 02:00:56.463] (WARN!) : [SystemManager] Populate system Favorites took : 6
...
[1980/01/01 02:00:56.723] (ERROR) : [MainRunner] Error while parsing systems configuration file!
[1980/01/01 02:00:56.725] (ERROR) : [MainRunner] IT LOOKS LIKE YOUR SYSTEMS CONFIGURATION FILE HAS NOT BEEN SET UP OR IS INVALID.
...
[1980/01/01 02:01:26.763] (INFO ) : [Main] EmulationStation cleanly shutting down.
[1980/01/01 02:01:26.764] (INFO ) : [Main] Regular Quit (or Fatal Error)

같은 흐름이 네 번의 부팅 로그에서 반복됐다. 따라서 커널 부팅 실패나 일시적인 멈춤이 아니라, EmulationStation이 매번 같은 조건에서 종료된 것으로 판단했다.

여기서 Final non-virtual visible systems: 127은 실제 표시 가능한 시스템 수가 아니다. 해당 로그 코드는 이름과 달리 mVisibleSystems.Count()가 아닌 mAllSystems.Count()를 출력한다. 따라서 로그의 127과 최종 표시 가능 시스템 0개는 서로 모순되지 않는다.

원인을 찾은 과정

1. 부팅 파일 무결성 확인

부팅 파티션의 핵심 파일을 boot.md5와 비교했다. 커널, initrd, recalbox 파일의 체크섬은 모두 일치했다. 적어도 부팅 이미지의 핵심 파일이 깨져서 발생한 문제는 아니었다.

2. 설정값 확인

SHARE/system/recalbox.conf에서 다음 두 값을 확인했다.

emulationstation.selectedsystem=favorites
emulationstation.favoritesonly=1

그런데 gamelist-userdata.ini와 기존 게임 목록 어디에도 즐겨찾기 메타데이터가 없었다. 즉, 즐겨찾기만 표시하도록 설정돼 있지만 실제 즐겨찾기는 0개인 상태였다.

3. Recalbox 10.0.8 소스 코드 추적

로그만 보면 systemlist.xml 같은 시스템 설정 파일이 잘못된 것처럼 보인다. 하지만 실제 코드 흐름은 달랐다.

1. FileData::BuildTopLevelFilter()는 favoritesonly가 켜져 있으면 최상위 즐겨찾기 필터를 추가한다.
2. SystemData::HasVisibleGame()은 이 필터를 통과하는 게임이 있는지 검사한다.
3. 즐겨찾기가 0개이면 모든 시스템의 표시 가능한 게임 수가 0이 된다.
4. SystemManager::LoadSystemConfigurations()은 표시할 시스템이 하나도 없을 때 마지막 줄에서 false를 반환한다.
5. MainRunner::TryToLoadConfiguredSystems()은 이 반환값을 시스템 설정 파일 파싱 실패로 해석하고 프런트엔드를 끝낸다.

정리하면 다음과 같은 흐름이다.

favoritesonly=1
        ↓
즐겨찾기 게임 0개
        ↓
필터를 통과하는 게임 0개
        ↓
표시 가능한 시스템 0개
        ↓
LoadSystemConfigurations()가 false 반환
        ↓
설정 파일 오류로 잘못 표시한 뒤 EmulationStation 종료

사용자가 메뉴에서 필터를 다시 끌 기회조차 얻지 못한다는 점이 이 문제의 핵심이다.

ROM을 지우지 않고 복구하는 방법

작업 전에는 Recalbox를 정상 종료하고 저장장치를 다른 PC에 연결한다. SHARE 파티션이 보이면 다음 파일을 먼저 복사해 백업한다.

SHARE/system/recalbox.conf

그다음 텍스트 편집기로 recalbox.conf를 열고 아래 값을 변경한다.

emulationstation.favoritesonly=0

emulationstation.favoritesonly 항목이 여러 개라면 중복 값을 모두 확인한다. 파일을 저장한 뒤 운영체제의 안전 제거 기능으로 저장장치를 분리하고 Recalbox에서 다시 부팅한다. 이 과정은 SHARE/roms, BIOS, 세이브 파일을 건드리지 않으므로 ROM을 삭제할 이유가 없다.

emulationstation.selectedsystem=favorites가 함께 있더라도 우선 favoritesonly만 0으로 바꾸어 테스트하는 편이 좋다. 이번 종료를 일으킨 핵심 조건은 favoritesonly=1과 즐겨찾기 0개의 조합이다.

설정 전체를 초기화하고 싶다면

설정만 초기화하는 방법도 있지만, 먼저 SHARE 전체를 백업하는 편이 안전하다. Recalbox 메뉴에 접근할 수 있다면 공장 초기화 기능을 사용할 수 있다. 메뉴가 열리지 않는 경우에는 다른 PC에서 SHARE/system의 설정 파일을 별도로 백업한 뒤 초기화 범위를 결정해야 한다.

이번 문제에는 전체 초기화보다 recalbox.conf의 한 줄을 수정하는 것이 가장 작고 안전한 해결책이다.

왜 버그라고 볼 수 있나

필터 결과가 비어 있는 것은 정상적으로 발생할 수 있는 UI 상태다. 즐겨찾기를 모두 해제하거나, 즐겨찾기 정보가 없는 새 목록을 가져오기만 해도 생길 수 있다.

이때 기대할 수 있는 동작은 다음 중 하나다.

• 빈 즐겨찾기 화면을 보여주고 필터를 해제할 수 있게 한다.
• 즐겨찾기가 0개이면 favoritesonly를 자동으로 끈다.
• 일반 시스템 목록으로 임시 복귀한다.

현재처럼 프런트엔드를 종료하고 “시스템 설정 파일이 잘못됐다”고 표시하는 것은 실제 원인과도 맞지 않으며, UI 안에서 복구할 방법도 막는다. 빈 필터 결과와 실제 시스템 설정 파싱 실패를 구분해야 한다.

Recalbox 프로젝트에 보고

동일한 제목과 설명으로 Recalbox GitLab에 재현 절차, 로그, 관련 코드 경로를 정리해 보고했다.

• 이슈: recalbox/recalbox#2572
• 대상 버전: Recalbox 10.0.8
• 제안: 표시 필터로 인해 시스템 수가 0이 된 경우 프런트엔드를 유지하고 UI 복구 경로 제공

공개 이슈에는 이메일 주소, GitLab 로그인 정보, 저장장치 식별자 같은 개인정보를 포함하지 않는다. 전체 로그를 첨부할 때도 네트워크 주소, 사용자 경로, 장치 일련번호가 들어 있는지 먼저 확인해야 한다.

마무리

초기 로딩까지 끝난 뒤 Recalbox가 사라지는 증상은 부팅 실패처럼 보여도 실제로는 EmulationStation 설정 문제일 수 있다. 특히 아래 조건을 먼저 확인하면 ROM 재설치나 전체 포맷을 피할 수 있다.

emulationstation.favoritesonly=1

즐겨찾기가 하나도 없다면 값을 0으로 바꾸고 다시 부팅해 보자. 이번 사례는 한 줄의 설정으로 정상적인 빈 목록이 치명적인 시작 오류로 바뀌는 전형적인 예외 처리 문제였다.