Fix: The sandbox is not in sync with the Podfile.lock in Xcode

Why this happens

CocoaPods adds a shell script build phase called Check Pods Manifest.lock to every target that uses pods. It runs before compilation and compares two files:

• Podfile.lock — the resolved dependency versions, checked into source control.
• Pods/Manifest.lock — a copy of that file written by pod install at the moment the sandbox was generated.

If the two files differ, the script prints error: The sandbox is not in sync with the Podfile.lock. Run 'pod install' or update your CocoaPods installation. and exits with a non-zero status, which stops the build. The message is accurate: the Pods folder on disk no longer matches the lockfile your project expects.

The usual trigger is a Podfile.lock that changed without a matching install — a git pull, a merge, a branch switch, or someone editing the Podfile. The second, sneakier cause is that the diff command itself cannot run because the ${PODS_ROOT} variable is empty or points somewhere else. In that case the files may be perfectly in sync, but diff fails on a missing path and the script reports the same error.

How to fix it

1. Run pod install from the right folder

This is the fix in the vast majority of cases. The command must run in the directory that contains the Podfile, not the .xcodeproj bundle and not a parent folder.

cd /path/to/ProjectFolder   # the folder with the Podfile
pod install
open YourApp.xcworkspace

Use pod install, not pod update. pod install respects the versions already pinned in Podfile.lock; pod update resolves new versions and rewrites the lockfile, which is a different operation and can pull in unrelated changes.

After it finishes, confirm the two files now match:

diff Podfile.lock Pods/Manifest.lock

No output means they are identical. Then build the workspace, never the project file — the Pods project is only part of the workspace build.

2. Remove stale libPods*.a references, then reinstall

Older projects often carry leftover static library links from a previous CocoaPods version. They do not cause the manifest error directly, but they break the build immediately afterwards and make it look like the fix failed.

1. Select the project in the navigator, then the target.
2. Open Build Phases → Link Binary With Libraries.
3. Delete every libPods*.a entry.
4. Run pod install again so CocoaPods re-adds what it needs.
5. Clean the build folder with Product → Clean Build Folder (Shift-Cmd-K) and rebuild.

3. Repair the manifest check script when ${PODS_ROOT} is empty

If diff Podfile.lock Pods/Manifest.lock shows no differences but Xcode still fails, the script phase is the problem. Open Build Phases → Check Pods Manifest.lock and look at the first line. Older CocoaPods versions generated this:

diff "${PODS_ROOT}/../Podfile.lock" "${PODS_ROOT}/Manifest.lock" > /dev/null

PODS_ROOT is defined in the generated Pods-<Target>.<config>.xcconfig, which must be set as the target’s base configuration. If that xcconfig is missing or was removed, the variable expands to nothing and the diff fails on a path like /../Podfile.lock.

The correct repair is to restore the base configuration: run pod install and check that Project → Info → Configurations points at the Pods xcconfig files. If you need to unblock the build right now, replace the line with absolute-from-source-root paths:

diff "${SRCROOT}/Podfile.lock" "${SRCROOT}/Pods/Manifest.lock" > /dev/null

This works only when the Pods folder really sits at ${SRCROOT}/Pods. It is a workaround, not a fix — the next pod install may regenerate the phase, and any target whose Pods live elsewhere will still fail.

4. Reset the sandbox completely

When the Pods folder is in an unknown state — half-deleted, generated by a different CocoaPods version, or merged badly — rebuild it from scratch while keeping your pinned versions:

rm -rf Pods
pod install

Deleting Pods/ is safe because Podfile.lock still records every version. Deleting Podfile.lock is not: you lose the pins and the next install may resolve newer, incompatible releases.

If the project has been through several CocoaPods upgrades, a full deintegrate is cleaner:

pod deintegrate
pod install

5. Update CocoaPods itself

Very old CocoaPods releases (0.29-era, as in the original report) generated script phases and xcconfigs that modern Xcode handles poorly. Check your version and update if it is far behind:

pod --version
gem install cocoapods

If the project has a Gemfile, use Bundler so everyone on the team runs the same CocoaPods version:

bundle install
bundle exec pod install

How to prevent it

• Commit Podfile.lock and treat it as source. Never edit it by hand.
• Run pod install after every git pull, merge, or branch switch that touches the Podfile or lockfile.
• Always open and build the .xcworkspace, not the .xcodeproj.
• Pin CocoaPods with a Gemfile so CI and teammates generate identical sandboxes.
• If you commit the Pods folder, commit it in the same commit as Podfile.lock — a mismatch is exactly what this error reports.
• Keep the Pods xcconfig files as the target’s base configuration; do not delete them while cleaning up build settings.

FAQ

Does pod update fix this error?

It can, because it rewrites Podfile.lock and regenerates Pods/Manifest.lock together. But it also upgrades dependencies to newer versions, which may introduce unrelated breakage. Use pod install unless you actually intend to move versions.

Is it safe to delete Podfile.lock?

No, not as a first move. It holds the exact resolved versions for every pod. Delete the Pods folder instead and run pod install — that regenerates the sandbox while keeping the same versions.

Why does the error appear only on a colleague’s machine or on CI?

Because their Pods folder was generated from a different Podfile.lock, or was never generated at all. A clean checkout needs pod install before the first build; CI should run it as an explicit step before xcodebuild.