native-build-errors

Native build failure triage

The one rule that matters

Native build logs bury the real error under hundreds of lines of noise. Always find the FIRST real error, not the last line. The last line is usually a generic "build failed" wrapper around the actual cause.

• Android: search the log for FAILURE: and Caused by:. The deepest Caused by: is the real one. Also look for > Task :app:... FAILED to identify which task died.
• iOS: search for error: (lowercase, with colon). Ignore warning:. When xcodebuild output is huge, the failing step name right above the first error: tells you which pod or script phase broke.

Never start by nuking caches. Read the error first. Cache-nuking is step 8, not step 1.

iOS playbook

pod install fails

• None of your spec sources contain a spec satisfying the dependency: the lockfile and Podfile disagree, usually after a branch switch or dependency bump. Start gentle: cd ios && pod install --repo-update. Only if that fails, remove Pods/ and Podfile.lock and reinstall; in an RN project the lockfile regenerates from package.json, which is why this is acceptable here and not for JS lockfiles (see the last-resort section).
• Ruby/ffi errors on Apple Silicon: the project's Ruby is too old or gems were built for the wrong arch. Prefer the version from .ruby-version. bundle install && bundle exec pod install beats global pods.
• could not find compatible versions for pod X: two libraries pin conflicting versions of a shared native dependency (common with Firebase and GoogleUtilities). Check which two, then upgrade the older library instead of pinning in the Podfile if possible.

Xcode build fails after pods succeeded

• No such module 'X': the pod exists but the workspace was not used, or DerivedData holds a stale module map. Confirm you opened .xcworkspace, then rm -rf ~/Library/Developer/Xcode/DerivedData.
• Duplicate symbols or use_frameworks! conflicts: static and dynamic linkage mixing, classic with Firebase. In Expo projects set useFrameworks: "static" via expo-build-properties instead of hand-editing the Podfile.
• Signing errors on device builds: set the development team in Xcode once, or use EAS credentials. Do not commit personal team IDs into the project file of a shared repo.
• A script phase fails (Hermes, sourcemaps, [CP-User]): open the phase's own log section. These phases inherit PATH from Xcode, not your shell, so tools installed via nvm or asdf may not resolve. Hardcoding node paths in .xcode.env.local fixes most of it.