Find where your iOS dependency failed
A package cache, build artifact, and signed app are different layers. Start with the first failed operation in Xcode’s Report navigator or the package manager’s output. Then follow the matching branch below. This path covers Swift Package Manager and CocoaPods without assuming that a clean or reinstall fixes every error.
1. Which manager owns the dependency?
If the project lists the library under Xcode Package Dependencies or has a Package.resolved file, follow the Swift package branch. If it has a Podfile, Podfile.lock, and generated Pods workspace, follow CocoaPods. A project can use both; identify the failing library rather than cleaning both systems.
2. Where did it fail?
| First failure | What to inspect | Next guide |
|---|---|---|
| Fetch or authentication | Repository URL, registry or spec source, account access, network, and first request error. | Swift package resolution · CocoaPods install log |
| Version selection | Declared constraints and pinned versions. Check whether the requested tag or podspec exists. | Package.resolved conflict · Missing pod specification |
| Compile or import | The first compiler error, importing target, target membership, and product name. | No such module · SwiftCompile failure |
| Link or embed | Missing framework, destination architecture, linked product, and whether a dynamic library is embedded. | Framework not found · Library not loaded |
| Only CI fails | Committed lockfile, private dependency permissions, Xcode version, and runner credentials. | Xcode Cloud build · Package.resolved in CI |
3. Choose the smallest cleanup
For a stale Swift package checkout, first preserve the original error and lockfile, then use Xcode’s package cache reset. For a standalone package with stale compiled output, compare clean and dependency resolution. These operations cannot grant access to a private Git repository or create a missing version tag.
For CocoaPods, clear one affected pod’s cache when its downloaded artifact is suspect. Use a clean install for stale generated integration. Keep Podfile.lock unless you deliberately intend to change versions; pod update is a version update, not a routine repair.
Before sharing an error
Include the first failing line, package name and requested version, Xcode and operating-system versions, destination (simulator or device), and whether the failure occurs locally, in CI, or both. Redact private repository URLs and credentials. An exit code or “failed to resolve” summary by itself rarely identifies the cause.
Primary documentation
- Apple: add package dependencies
- Apple: Swift packages in CI
- Swift: package dependency resolution
- CocoaPods: install versus update
This guide organizes documented checks into a diagnostic sequence. The exact commands and menus depend on your toolchain and project.