How to Fix CocoaPods “The sandbox is not in sync with the Podfile.lock”

When building an iOS project that uses CocoaPods, Xcode may stop with the message The sandbox is not in sync with the Podfile.lock. This usually means the installed Pods and the dependency versions recorded in Podfile.lock no longer match.

What causes this error?
Typical situations
How to check the problem
Solution 1: Run pod install
Solution 2: Reopen the .xcworkspace file
Solution 3: Reinstall the Pods directory
Solution 4: Clear Xcode build data
Solution 5: Reintegrate CocoaPods
Solution 6: Check Git conflicts in Podfile.lock
Important notes
Summary

What causes this error?

CocoaPods uses Podfile.lock to record the resolved dependency versions and Pods/Manifest.lock to describe what is currently installed in the Pods directory. If these files differ, CocoaPods detects that the local sandbox is out of sync.

Podfile or Podfile.lock changed after the last pod install.
A project was pulled from Git but the Pods directory was not regenerated.
Two branches contain different Pod dependencies.
Pods was deleted or partially restored.
The project was opened from the .xcodeproj file instead of the CocoaPods-generated .xcworkspace.

Typical situations

The error often appears immediately after switching Git branches, merging dependency changes, updating a Pod, cloning the repository on another Mac, or removing the Pods directory to troubleshoot another build problem.

How to check the problem

From the directory that contains the Podfile, first confirm that the lock files exist.

ls Podfile.lock
ls Pods/Manifest.lock

You can then compare them directly.

diff Podfile.lock Pods/Manifest.lock

If the command shows differences, the installed Pods do not match the dependency state recorded by CocoaPods.

Solution 1: Run pod install

In most cases, the safest fix is to run pod install in the project directory.

cd /path/to/your/project
pod install

This installs the dependency versions described by the Podfile and lock file and regenerates the CocoaPods workspace when necessary.

Use pod install when you want to reproduce the dependency versions already recorded in Podfile.lock. Do not use pod update merely as a substitute, because it can resolve newer dependency versions.

Solution 2: Reopen the .xcworkspace file

Close Xcode and open the workspace generated by CocoaPods instead of the original project file.

open YourProject.xcworkspace

If you open YourProject.xcodeproj, the Pods integration may not be loaded correctly.

Solution 3: Reinstall the Pods directory

If the local Pods directory is damaged or stale, remove it and install the dependencies again.

rm -rf Pods
pod install

Afterward, reopen the .xcworkspace file and rebuild the project.

Solution 4: Clear Xcode build data

If CocoaPods is already synchronized but Xcode still reports an old build-state error, clear Derived Data and rebuild.

rm -rf ~/Library/Developer/Xcode/DerivedData/*

You can also use Product > Clean Build Folder in Xcode.

Solution 5: Reintegrate CocoaPods

When the CocoaPods integration itself appears broken, you can remove the existing integration and regenerate it.

pod deintegrate
pod install

This is more invasive than a normal pod install, so try the simpler solutions first.

Solution 6: Check Git conflicts in Podfile.lock

If the error started after a merge, inspect Podfile.lock for unresolved conflict markers or dependency versions that do not match the selected branch.

git status
git diff -- Podfile.lock

Resolve the conflict correctly, then run:

pod install

Important notes

Avoid deleting Podfile.lock without a reason. In application projects, it helps keep dependency versions consistent across machines and CI environments.
Running pod update may change dependency versions, so use it only when you intentionally want to update Pods.
If CocoaPods itself cannot run, check the installed version with pod --version and verify that the Ruby/CocoaPods environment is working.
After regenerating Pods, always build from the .xcworkspace file.

Summary

The sandbox is not in sync with the Podfile.lock means that CocoaPods has detected a mismatch between the dependency state recorded in Podfile.lock and the Pods currently installed in the project. Start with pod install, reopen the .xcworkspace, and only then move on to reinstalling Pods, clearing Derived Data, or running pod deintegrate. In projects managed with Git, also check whether Podfile.lock changed during a branch switch or merge.