CocoaPods Common Issues

Issues with Installing CocoaPods

Execute pod --version to check if CocoaPods is installed and view the version number.

Open Terminal (⌘ + Space, type Terminal to open the terminal), and execute:

sudo gem install cocoapods

sudo gem install cocoapods

For more details, please refer to CocoaPods Getting Started.

Issues with Connecting to trunk CDN

Since version 1.8, CocoaPods uses trunk CDN (https://cdn.cocoapods.org/) as the spec source by default. The original intention is very good, avoiding the need to locally clone a large Specs repository, which would require a full update every time. However, it may not be possible to access this trunk CDN domestically.

Common issues:

1. When executing pod install, the error CDN: trunk URL couldn't be downloaded is reported.

2. When executing pod repo update, the error CDN: trunk Repo update failed is reported.

The following are several solutions.

Solution 1: Use a Proxy

Whether using an older version of CocoaPods or using a mirror source, neither is the optimal solution. To fully utilize the features of CocoaPods, the most recommended solution is to use a proxy to solve the problem of not being able to connect to the trunk CDN.

Solution 2: Use an Older Version of CocoaPods

CocoaPods version 1.7.5 uses Specs as the repo source by default. You can uninstall and reinstall an older version of CocoaPods.

• Uninstall:

sudo gem uninstall cocoapods

sudo gem uninstall cocoapods

• Install CocoaPods 1.7.5:

sudo gem install cocoapods -v 1.7.5

sudo gem install cocoapods -v 1.7.5

Solution 3: Manually Switch to Using Official Git Source/Mirror Source

1. Check the current source being used

   First execute pod repo list to see what sources are on your machine. If there is a master source (URL: https://github.com/CocoaPods/Specs.git) and a trunk source (URL: https://cdn.cocoapods.org/), you don't need to perform the second step below. You can directly execute pod repo remove trunk to delete the trunk CDN source.

   If using version 1.9.1 or above, there should only be one trunk CDN source. In this case, you need to manually add a Git source.

2. Add source

   • Add Official CocoaPods Git Source.

     Execute pod repo add cocoapods https://github.com/CocoaPods/Specs.git.

   • Add Tsinghua CocoaPods Mirror Source.

     Execute pod repo add tuna https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git.

3. Execute pod repo update --verbose.

4. Specify the source in the Podfile file in the root directory of the iOS project.

Add a line source https://xxxxx.git to the first line of Podfile (where the URL is the URL of the source added in the previous step).

Example: Using Tsinghua source

source 'https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git'

target 'MyProject' do
  use_frameworks!
end

source 'https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git'

target 'MyProject' do
  use_frameworks!
end

If you don't specify source in the Podfile, CocoaPods version 1.8 and above will automatically re-add and use the trunk CDN source. Therefore, each project's Podfile needs to explicitly specify the source, which is very cumbersome.

Issues with pod install Unable to Find the Project

When executing pod install, you may encounter the following error: Unable to find a specification for "XXXXXX" or CocoaPods could not find compatible versions for pod "XXXXXX"

The following are several solutions.

Solution 1: Update Index

1. Execute pod repo update --verbose to update the index.

2. Then execute pod update XXXXXX to update the library (XXXXXX is the name of the specific library that reported the error in the prompt).

3. Finally, execute pod install to reinstall.

Solution 2: Delete Index File and Reload

1. Execute pod setup.

2. Then execute rm ~/Library/Caches/CocoaPods/search_index.json to delete the index file.

3. Finally, execute pod install to reinstall (may take a long time).