'CocoaPods not installed or not in valid state' 오류 해결하기

최근 플러터 앱을 개발하는 과정에서 매우 이상한 오류를 겪었습니다.

분명 얾마 전까지만 해도 iOS 앱 빌드 및 실행에 문제가 없었는데, 갑가지 아래와 같이 Cocoapods 오류가 발생하며 앱 실행이 되지 않았습니다.

Launching lib/main.dart on iPhone 12 Pro in debug mode...
Warning: CocoaPods is installed but broken. Skipping pod install.
  You appear to have CocoaPods installed but it is not working.
  This can happen if the version of Ruby that CocoaPods was installed with is different from the one being used to invoke it.
  This can usually be fixed by re-installing CocoaPods. For more info, see https://github.com/flutter/flutter/issues/14293.
To re-install:
  sudo gem install cocoapods

CocoaPods not installed or not in valid state.
Error launching application on iPhone 12 Pro.

오류 메시지에 나와 있는 이슈 링크는 엉뚱한(?) 이슈로 연결되어 크게 도움을 얻지 못했고, 구글링을 해 보니 flutter/issues/54962에서 도움이 될 만한 내용을 찾을 수 있었습니다.

이 경우 확인해봐야 하는 절차는 크게 다음과 같습니다.

CocoaPods가 애초에 설치되어 있지 않은 경우

flutter doctor -v 를 실행하여 CocoaPods 설치 상태를 확인합니다. 아래와 같이 설칟된 CocoaPods 버전이 정상적으로 출력되어야 합니다.

[✓] Xcode - develop for iOS and macOS
  • Xcode at /Applications/Xcode.app/Contents/Developer
  • Xcode 12.4, Build version 12D4e
  • CocoaPods version 1.10.1

만약 CocoaPods가 설치되어 있지 않다면 CocoaPods 설치 가이드를 참조하여 설치를 진행하면 되며, 설치가 완료되면 문제가 해결됩니다.

Homebrew를 사용하여 CocoaPods를 설치 (brew install cocoapoods)할 수도 있습니다.

CocoaPods는 설치되어 있으나 모종의 이유로(?) 설치가 꼬인 경우

최근에 OS 업데이트를 진행했다면, 커맨드 라인 도구 (특히 루비랑 관련된 도구들)이 엉망이 되었을 가능성이 높습니다. (저도 매번 업데이트 할 때마다 당하고 있습니다..ㅠㅠ)

sudo gem uninstall cocoapods를 실행하여 설치된 CocoaPods를 완전히 제거한 후 Cocoapods를 다시 설치하면 문제를 해결할 수 있습니다.

안드로이드 스튜디오가 이상해진 경우

제가 이 케이스였습니다. CocoaPods를 아무리 재설치해도 문제가 해결되지 않고, flutter doctor에서도 CocoaPods를 정상적으로 인식하고 있던 상태였습니다.

혹시나 해서(?) 안드로이드 스튜디오 메뉴에서 File > Invalidate Caches / Restart를 실행하니, 거짓말같이 문제가 해결되었습니다. -_-;;

기존에 CocoaPods를 잘 쓰다가 갑자기 이 문제를 마주하게 되는 경우, 저처럼 고생하지 마시고 이 방법부터 먼저 시도해보시길 추천합니다 :)