Fix 'The sandbox is not in sync with the Podfile.lock' Error in Xcode iOS Projects

The Error

You hit Build. Nothing happens — except this:

error: The sandbox is not in sync with the Podfile.lock. Run 'pod install' or update your CocoaPods installation.

Dead stop. Not a single line of your code compiled. This almost always hits right after pulling new code from git, switching branches, or when a teammate updated the Podfile and committed the changes without telling anyone to re-run pod install.

Why This Happens

CocoaPods keeps your dependencies in the Pods/ directory (the "sandbox"). The Podfile.lock records the exact versions that should be there — think of it as a receipt. When the receipt and the actual contents don't match, Xcode's build phase script catches it and refuses to continue.

The most common triggers:

Someone added or updated a Pod and pushed a new Podfile.lock, but you haven't run pod install yet
You switched branches where Pod versions differ
The Pods/ directory got deleted or corrupted
A teammate ran pod update (which upgrades versions) instead of pod install
CocoaPods itself was updated and produced a slightly different lockfile format

Step-by-Step Fix

Step 1: Run pod install (solves it 80% of the time)

From the directory containing your Podfile — usually the project root:

cd /path/to/your/project
pod install

Once it finishes, open the .xcworkspace file — not .xcodeproj. Always the workspace. Build again and you're likely done.

Step 2: Refresh the spec repo first

Still failing? Your local CocoaPods spec cache might be stale. Sync it before installing:

pod repo update
pod install

Stale specs are sneaky — they can cause pod install to silently skip updates while reporting success. The repo update pulls fresh metadata from the CocoaPods CDN.

Step 3: Nuke the Pods directory and reinstall

When the error sticks around, the Pods/ directory itself is probably in a bad state. Delete it and start clean:

rm -rf Pods/
pod install

This keeps your Podfile.lock intact, so you'll reinstall the exact same versions — no surprise upgrades.

Only delete Podfile.lock if you want to allow version upgrades within the ranges your Podfile specifies:

rm -rf Pods/
rm -f Podfile.lock
pod install

Be careful with this one. It can pull in newer Pod versions that introduce breaking changes.

Step 4: Wipe Xcode's derived data

Xcode caches build artifacts aggressively. Sometimes stale cache files survive a clean pod install and keep the error alive. Clear them:

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

Prefer clicking? Inside Xcode: Settings → Locations → Derived Data → click the arrow → delete your project's folder. Then hit Product → Clean Build Folder (Shift+Cmd+K) and rebuild.

Step 5: Update CocoaPods itself

Version mismatches between teammates cause subtle lockfile incompatibilities. If your colleague is on CocoaPods 1.15 and you're still on 1.12, the lockfile format can differ enough to trigger this error every single time.

Update with gem:

sudo gem install cocoapods

Or via Homebrew:

brew upgrade cocoapods

Then run pod install again. Check your version with pod --version and compare it with your team.

Step 6: Check the Xcode build phase script

Rarely, the build phase that validates sandbox sync gets corrupted or misconfigured. Open Xcode and look at your target:

Select your Target → Build Phases
Find the phase called [CP] Check Pods Manifest.lock
The script inside does a diff between PODS_PODFILE_DIR_PATH/Podfile.lock and PODS_ROOT/Manifest.lock

Missing or empty? CocoaPods wasn't properly integrated into the build. Re-running pod install regenerates the correct build phases automatically.

Verification

Before trusting the build, confirm the two lock files are actually in sync:

# No output = files match = you're good
diff Podfile.lock Pods/Manifest.lock

Silence is success. Any output means there's still a mismatch — revisit Step 3.

Want to double-check installed versions? Run:

pod list

Cross-reference that with what's in Podfile.lock. Everything should line up.

Preventing This in the Future

Always commit Podfile.lock — non-negotiable for team projects. It's the only way to guarantee everyone installs identical versions.
Keep Pods/ out of git — add it to .gitignore. Each developer runs pod install locally after pulling.
Make pod install a pull habit — any time you see Podfile or Podfile.lock in the diff, run it before building.
Know the difference between pod install and pod update — install respects the lockfile; update upgrades to latest versions. Never run pod update unless you specifically intend to upgrade dependencies and are prepared to test the result.

Quick Reference

# Standard fix
cd /path/to/project
pod install

# Clean fix (preserves locked versions)
rm -rf Pods/
pod install

# Nuclear option (allows version upgrades)
rm -rf Pods/ Podfile.lock
pod install

# Also clear Xcode cache
rm -rf ~/Library/Developer/Xcode/DerivedData