CocoaPods PBXFileSystemSynchronizedRootGroup 오류 (Xcode 16 )

Xcode 16으로 업그레이드한 뒤에 CocoaPods를 쓰려고 pod init을 실행했는데,
아래와 같은 오류가 자주 발생한다.

RuntimeError - `PBXGroup` attempted to initialize an object with unknown ISA `PBXFileSystemSynchronizedRootGroup`

 

이 문제를 해결하는 가장 빠르고 간단한 방법 중 하나는
프로젝트 내에 “Folder”로 표시된 디렉터리를 전부 “Group”으로 변환해주는 것이다.

문제가 해결이 우선이라면 여기까지만 읽어도 해결이 될듯하다.

---

핵심 해결 방법

1. Xcode 프로젝트 열기
2. 프로젝트 트리(좌측 Navigator)에서 폴더 아이콘으로 표시된 디렉터리를 우클릭
3. “Convert to Group” 메뉴가 있으면 선택하여 폴더를 그룹으로 변환

만약 이미 Group 상태라면 “Convert to Folder”라고 표시될 텐데,
이 경우에는 한 번 “Convert to Folder”로 바꿨다가 다시 “Convert to Group”을 적용하는 방식으로 진행하면 된다.

 

막상 해결방법은 찾았는데 Folder와 Group의 차이가 정확하게 뭔지 모르는것 같아서 정리해본다.

Folder와 Group의 차이

• Folder:
  실제로 macOS 파일 시스템에 존재하는 디렉터리 자체를 가리킨다.
  Xcode 외부에서도 동일하게 폴더로 인식되며, Finder에서도 실제로 폴더 구조가 반영된다.
• Group:
  Xcode 상에서만 논리적으로 묶어놓은 가상 디렉터리(일종의 “레이블” 같은 개념).
  macOS의 실제 파일 구조와 꼭 1:1로 대응하지 않아도 되며, Xcode 프로젝트 내부적으로만 구조를 깔끔히 정리하기 위해 사용

일반적으로 Xcode에서 Swift나 Objective-C 소스 파일을 정리할 때는
실제 폴더보다는 Group을 사용하는 편이 프로젝트 관리를 더 유연하게 해주기 때문에 사용한다고 하는데... 사례는 좀더 찾아봐야겠다. 일단 프로젝트 진행이 먼저기에...
(프로젝트 폴더 구조와 상관없이 원하는 대로 그룹화가 가능하다고 하는데...)

---

추가 해결책(참고)

만약 Folder → Group 변환만으로도 해결이 안 된다면, 다음 작업을 시도할 수 있습니다.

1. Xcode 완전히 종료
2. YourProject.xcodeproj → 우클릭 → “Show Package Contents” → project.pbxproj 파일 열기
3. 텍스트 에디터에서
   • PBXFileSystemSynchronizedRootGroup이 있으면 모두 PBXGroup으로 일괄 변환
   • objectVersion이 77 등의 높은 값이면, pod install 시 경고에 나온 권장 버전(예: 56, 63)으로 수정
   • 혹은 minimizedProjectReferenceProxies, preferredProjectObjectVersion 같은 설정을 제거
4. 파일 저장 후, 다시 터미널에서 pod deintegrate && pod setup && pod install 등 재시도

---

정리하자면,
Xcode 16에서 CocoaPods 사용 시 발생하는 PBXFileSystemSynchronizedRootGroup 에러는
주로 폴더 구조에 관한 Xcode 내부 설정 이슈로 인해 생기는 문제라고 한다.