Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Unity iOS build fails while External Dependency Manager runs CocoaPods

ErrorWARNING: 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.

  • Applies to Unity 6, External Dependency Manager for Unity, CocoaPods
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 install
  2. 2Match what you see, then jump to its fix

    1. 1WARNING: CocoaPods requires your terminal to be using UTF-8 encoding.The terminal locale is not UTF-8Fix
    2. 2pod no longer works right after a macOS upgradeCocoaPods itself is broken or missing after a macOS upgradeFix
    3. 3Permission errors in ~/Library/Caches/CocoaPods, ~/.cocoapods or the Pods folderFiles left by running CocoaPods as root block a normal runFix
    4. 4The build runs on a cloud build service and the pod step fails there onlyThe build service cannot open an Xcode workspaceFix

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 --version

2Fix

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 ~/.zprofile

3Verify

pod install now finishes without the warning.

pod install

Confirmed by raw.githubusercontent.com

Did this fix it?

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 --version

2Fix

Uninstall and install the CocoaPods gem again.

gem uninstall cocoapods
gem install cocoapods

3Verify

pod prints its version and pod install runs in the exported folder.

pod --version

Confirmed by guides.cocoapods.org

Did this fix it?

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 Pods

2Fix

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 install

3Verify

pod install finishes and creates the .xcworkspace.

ls *.xcworkspace

Confirmed by guides.cocoapods.org

Did this fix it?

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 Integration

2Fix

Set Cocoapods Integration to Xcode project in the iOS Resolver settings.

# Cocoapods Integration: Xcode project

3Verify

Run the cloud build again. The Podfile step passes.

# re-run the build in your build service

Confirmed by raw.githubusercontent.com

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.