Unity iOS build fails while External Dependency Manager runs CocoaPods
WARNING: CocoaPods requires your terminal to be using UTF-8 encoding.Short answer
Unity's iOS Resolver writes a Podfile and runs the pod tool after the build. If that run fails, the framework or Firebase addition fails. Run pod install yourself in the exported Xcode folder to read the real error. Usual fixes: set a UTF-8 locale, reinstall CocoaPods, or clear caches left by root.
Fix it fast
1Find out which cause you have
Run CocoaPods yourself in the folder Unity exported, the one that holds the Podfile. Its output is the real error that Unity only summarises.
cd /path/to/UnityExportedXcodeProject pod install2Match what you see, then jump to its fix
- 1
WARNING: CocoaPods requires your terminal to be using UTF-8 encoding.The terminal locale is not UTF-8Fix - 2
pod no longer works right after a macOS upgradeCocoaPods itself is broken or missing after a macOS upgradeFix - 3
Permission errors in ~/Library/Caches/CocoaPods, ~/.cocoapods or the Pods folderFiles left by running CocoaPods as root block a normal runFix - 4
The build runs on a cloud build service and the pod step fails there onlyThe build service cannot open an Xcode workspaceFix
- 1
What does the error look like?
WARNING: CocoaPods requires your terminal to be using UTF-8 encoding.
Cause 1 of 4
The terminal locale is not UTF-8
1Check
On a Mac the pod install can fail because of the language locale or UTF-8 encoding. The Unity resolver's guide says the problem appears in CocoaPods 1.11 and newer.
locale
pod --version2Fix
Export a UTF-8 locale in your shell profile, restart Unity from that shell, and build again. Alternatively run pod install in the terminal and open the generated .xcworkspace.
echo 'export LANG=en_US.UTF-8' >> ~/.zprofile
source ~/.zprofile3Verify
pod install now finishes without the warning.
pod installConfirmed by raw.githubusercontent.com
Cause 2 of 4
CocoaPods itself is broken or missing after a macOS upgrade
1Check
The CocoaPods guide says to reinstall the gem after upgrading macOS.
which pod && pod --version2Fix
Uninstall and install the CocoaPods gem again.
gem uninstall cocoapods
gem install cocoapods3Verify
pod prints its version and pod install runs in the exported folder.
pod --versionConfirmed by guides.cocoapods.org
Cause 3 of 4
Files left by running CocoaPods as root block a normal run
1Check
Since CocoaPods 0.32.0, running pod commands as root is not supported. Root-owned caches from earlier runs cause permission errors.
ls -ld ~/Library/Caches/CocoaPods ~/.cocoapods/repos/master Pods2Fix
Delete the root-owned files, then run pod install again as your own user.
sudo rm -fr ~/Library/Caches/CocoaPods/
sudo rm -fr ~/.cocoapods/repos/master/
sudo rm -fr Pods/
pod install3Verify
pod install finishes and creates the .xcworkspace.
ls *.xcworkspaceConfirmed by guides.cocoapods.org
Cause 4 of 4
The build service cannot open an Xcode workspace
1Check
In environments that cannot open workspaces, such as Unity Cloud Build, the resolver needs a different integration strategy.
# Unity: Assets > External Dependency Manager > iOS Resolver > Settings > Cocoapods Integration2Fix
Set Cocoapods Integration to Xcode project in the iOS Resolver settings.
# Cocoapods Integration: Xcode project3Verify
Run the cloud build again. The Podfile step passes.
# re-run the build in your build serviceConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Build iOS from a shell that already has LANG=en_US.UTF-8, so the pod step is the same on every Mac.
- Enable verbose logging in the iOS Resolver settings, so a failure shows its full output.
- Never run pod commands with sudo.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Mobile apps
Cannot change the App Privacy answers in App Store Connect
Publish Your App Privacy Responses?
Only the Account Holder, Admin and App Manager roles can answer the App Privacy questions.
2 causes, each with a fixMobile apps
App record creation fails because you lack permission
You cannot add a new app in App Store Connect as a Developer or limited user
Only the Account Holder, an Admin or an App Manager can create an app record, and Apple blocks it until the Account Holder has signed the latest agreement.
3 causes, each with a fixMobile apps
You cannot find the button to pull your app back from review
No 'remove this version from review' message appears on the version page
There is no button called Reject Binary.
3 causes, each with a fixMobile apps
Your Apple Account cannot sign in to App Store Connect
Sign-in to App Store Connect is refused for an account that should have access
App Store Connect does not open to every Apple Account.
3 causes, each with a fixMobile apps
Apple rejected the app under Guideline 4.3, Design: Spam
Guideline 4.3(b) - Design - Spam
Guideline 4.3 is Apple's duplicate rule.
5 causes, each with a fixMobile apps
App Store Connect rejects a screenshot because it has transparency
Images can't include alpha channels or transparencies.
App Store Connect does not accept screenshots that carry an alpha channel or transparent pixels.
2 causes, each with a fix