beautifulsoups.dev
Published on

Flutter iOS 빌드 실패? CocoaPods 오류 7분 해결

Authors

서론

Flutter로 iOS 빌드를 돌리다 보면 갑자기 pod install 단계에서 멈추거나, Xcode 빌드에서 Pods-Runner 관련 에러가 연쇄적으로 터지는 순간이 옵니다. 특히 CocoaPods could not find compatible versions, Specs satisfying the dependency were found, but they required a higher minimum deployment target, The sandbox is not in sync with the Podfile.lock 같은 메시지는 한 번 꼬이면 해결 루트가 복잡해 보이지만, 실제로는 원인 범주가 꽤 정형화되어 있습니다.

이 글은 “Flutter iOS 빌드 실패 + CocoaPods 오류”를 7분 안에 정리해서 복구하는 실전 루틴을 제공합니다. 핵심은 아래 3가지를 빠르게 분리하는 것입니다.

  • 로컬 캐시, 잠금 파일, 파생 데이터 등 “상태” 문제인지
  • iOS 최소 버전, Pod 호환성 등 “설정” 문제인지
  • Ruby, CocoaPods, Xcode CLI 등 “툴체인” 문제인지

문제 해결 스타일이 비슷한 트러블슈팅 글로는 GitLab CI Runner에서 Docker 권한 오류 해결 가이드, systemd 서비스가 계속 재시작될 때 원인 9가지도 참고할 만합니다. 증상은 달라도, “원인 범주를 좁히고 상태를 초기화한 뒤 재현 로그로 확정”하는 흐름이 동일합니다.

0분: 먼저 확인할 전제 (가장 흔한 함정)

아래 전제가 깨져 있으면 어떤 조치도 헛수고가 되기 쉽습니다.

  • Xcode가 설치되어 있고, Command Line Tools가 올바른 버전을 가리키는지
  • Flutter가 iOS 툴체인을 정상 인식하는지
  • ios 폴더가 Flutter 프로젝트의 표준 구조인지

다음 명령으로 빠르게 확인합니다.

xcode-select -p
xcodebuild -version
flutter doctor -v

flutter doctor -v에서 iOS 관련 항목이 빨간색이면, CocoaPods 이전에 Xcode CLI 경로부터 정리해야 합니다.

1분: “7분 루틴” 한 방에 정리하는 초기화 스크립트

CocoaPods 관련 오류는 1차적으로 “상태 꼬임”이 매우 많습니다. 아래는 가장 안전하고 재현성이 좋은 초기화 루틴입니다.

주의: 아래 작업은 ios/Podfile.lock과 Pods/를 재생성합니다.

flutter clean
rm -rf ios/Pods ios/Podfile.lock
rm -rf ~/Library/Developer/Xcode/DerivedData/*

cd ios
pod deintegrate
pod repo update
pod install
cd ..

flutter pub get
flutter build ios --debug

여기까지로 해결되면 원인은 대개 아래 중 하나입니다.

  • Podfile.lock과 실제 설치된 Pods의 불일치
  • Xcode DerivedData의 캐시 꼬임
  • 로컬 spec repo가 오래되어 신규 Pod 버전을 못 찾는 문제

그래도 실패한다면, 에러 메시지를 기준으로 분기해야 합니다.

2분: The sandbox is not in sync with the Podfile.lock

가장 흔한 오류 중 하나입니다. 의미는 단순합니다. Podfile.lock에 기록된 해시와 현재 Pods/ 상태가 다릅니다.

해결은 아래 중 하나로 끝나는 경우가 많습니다.

cd ios
pod install

그래도 반복되면 완전 초기화로 갑니다.

cd ios
pod deintegrate
rm -rf Pods Podfile.lock
pod install

CI 환경에서도 자주 보이는데, 이 경우 캐시 전략이 Pods 상태를 꼬이게 만들 수 있습니다. CI에서 Pods 캐시를 쓸 때는 Podfile.lock과 Pods 디렉터리를 “세트”로 다루는 것이 안전합니다.

3분: required a higher minimum deployment target

예시 메시지 형태는 보통 이렇습니다.

  • Specs satisfying the dependency were found, but they required a higher minimum deployment target

즉, 어떤 Pod가 iOS 최소 버전을 더 높게 요구합니다. 해결은 ios/Podfile의 플랫폼 버전을 올리는 것입니다.

Podfile을 열어 아래처럼 조정합니다.

platform :ios, '13.0'

그 다음 다시 설치합니다.

cd ios
pod install

Flutter 쪽 최소 버전도 같이 확인

ios/Runner.xcodeproj 또는 Runner.xcworkspace의 Deployment Target이 Podfile과 다르면 경고 또는 빌드 실패로 이어질 수 있습니다.

  • Xcode에서 Runner 타겟 선택
  • Build Settings에서 iOS Deployment Target 확인

Podfile과 Runner의 최소 버전은 보통 동일하게 맞추는 게 안전합니다.

4분: CocoaPods could not find compatible versions (버전 충돌)

이 메시지는 “Pod A는 Pod B의 특정 버전을 원하는데, 현재 잠금 파일 또는 다른 의존성이 충돌”하는 상황입니다.

우선 Podfile.lock을 삭제하고 재해결을 유도해 봅니다.

rm -rf ios/Podfile.lock ios/Pods
cd ios
pod install

그래도 충돌이 유지되면, 다음을 확인합니다.

  • pubspec.yaml에서 플러그인 버전을 올리거나 내리기
  • 문제가 되는 플러그인의 iOS Pod 의존성이 최근에 바뀌었는지
  • 특정 플러그인이 iOS 최소 버전을 올렸는지

자주 쓰는 진단: Pod 업데이트 범위를 좁히기

전체 업데이트는 오히려 충돌을 키울 수 있습니다. 문제 Pod만 업데이트해 확인합니다.

cd ios
pod update FirebaseCore
pod install

어떤 Pod가 충돌의 진앙인지 로그에 등장하는 “첫 번째 충돌 Pod”를 기준으로 좁히는 것이 시간 절약에 좋습니다.

5분: ffi / Ruby / CocoaPods 자체가 깨진 경우

특히 macOS 업데이트 이후 또는 Ruby 버전을 바꾼 뒤에 아래 유형이 자주 발생합니다.

  • LoadError - cannot load such file -- ffi_c
  • You don't have write permissions for the ... Gems
  • CocoaPods is installed but broken

이 경우는 프로젝트 문제가 아니라 로컬 Ruby 및 gem 환경 문제일 가능성이 큽니다.

1) CocoaPods 버전 확인 및 재설치

pod --version
which pod

Homebrew로 설치했는지, gem으로 설치했는지 경로가 섞이면 문제가 납니다. 하나로 통일하는 편이 안전합니다.

Homebrew 기반 재설치 예시:

brew uninstall cocoapods
brew install cocoapods
pod setup

gem 기반 재설치 예시:

sudo gem uninstall cocoapods
sudo gem install cocoapods
pod setup

회사 정책 등으로 sudo가 곤란하면, rbenv 또는 asdf로 사용자 영역 Ruby를 구성하는 편이 장기적으로 안정적입니다.

2) ffi 오류 빠른 복구

sudo gem uninstall ffi
sudo gem install ffi -- --enable-libffi-alloc

환경에 따라 옵션이 다를 수 있으니, 핵심은 “현재 Ruby 버전과 호환되는 ffi 바이너리/컴파일”을 다시 맞추는 것입니다.

6분: pod install은 되는데 Xcode에서 Pods-Runner 빌드 실패

이 경우는 Workspace를 잘못 열었거나, 빌드 설정이 꼬였을 가능성이 큽니다.

  • 반드시 Runner.xcworkspace를 열어야 합니다. Runner.xcodeproj를 열면 Pods가 링크되지 않아 실패할 수 있습니다.

또한 Apple Silicon에서 시뮬레이터 아키텍처 이슈가 섞이면 Excluded Architectures 관련 메시지가 나올 수 있습니다. Flutter 최신 버전에서는 많이 줄었지만, 레거시 프로젝트에서는 여전히 등장합니다.

Workspace 확인

ls ios | grep Runner.xcworkspace

있다면 Xcode에서 해당 파일을 열고 빌드합니다.

7분: 그래도 안 되면 로그를 “재현 가능한 형태”로 정리

CocoaPods 오류는 결국 로그가 답입니다. 아래 3가지를 확보하면 원인 추적 속도가 확 올라갑니다.

  1. Flutter 및 Xcode 버전
flutter --version
xcodebuild -version
pod --version
ruby -v
  1. Pod 설치 로그를 자세히
cd ios
pod install --verbose
  1. Flutter 빌드 로그
flutter build ios -v

이 상태에서 실패 메시지의 “첫 에러 블록”을 기준으로 위 섹션 중 어디에 해당하는지 매핑하면 됩니다. 특히 CocoaPods는 에러가 연쇄적으로 나오기 때문에, 맨 아래쪽의 마지막 에러보다 “처음 충돌을 선언한 줄”이 실제 원인인 경우가 많습니다.

자주 쓰는 최종 체크리스트 (복붙용)

아래는 실무에서 가장 자주 해결되는 순서대로 정리한 체크리스트입니다.

# 1) 툴체인 확인
xcode-select -p
xcodebuild -version
flutter doctor -v

# 2) Flutter/Pods 상태 초기화
flutter clean
rm -rf ios/Pods ios/Podfile.lock
rm -rf ~/Library/Developer/Xcode/DerivedData/*

# 3) CocoaPods 재설치/동기화
cd ios
pod deintegrate
pod repo update
pod install
cd ..

# 4) 다시 빌드
flutter pub get
flutter build ios --debug -v

마무리

Flutter iOS 빌드의 CocoaPods 오류는 복잡해 보이지만, 실제로는 “상태 초기화”, “iOS 최소 버전 상향”, “Pod 버전 충돌 해결”, “Ruby 및 CocoaPods 툴체인 복구” 네 갈래로 대부분 정리됩니다. 위 7분 루틴을 그대로 따라가면, 최소한 문제 범위를 정확히 좁혀서 다음 액션을 확정할 수 있습니다.

추가로 CI에서 iOS 빌드를 돌리는 경우, 캐시 전략과 동시 실행이 꼬여 비결정적으로 실패하는 패턴도 있습니다. 이런 경우에는 GitHub Actions 동시 실행 막힘 해결 - concurrency·cancel-in-progress처럼 “동시 실행 제어”까지 함께 점검하는 것이 안정화에 도움이 됩니다.

Discuss on Twitter • View on GitHub