Why every React Native upgrade takes longer than you estimated (and how to estimate honestly)

Almost every React Native upgrade I've worked on was estimated in days and delivered in weeks.
It's not that engineers estimate badly. It's that the estimate usually covers the wrong thing.

What we usually estimate

"Bump react-native, fix whatever the Upgrade Helper diff says, run the app."
That's the visible part of the work. The React Native Upgrade Helper
is excellent at it: it shows the file-by-file changes between two versions of a fresh template.

What actually takes the time

Native dependencies. Every library with an ios/ or android/ folder is a separate upgrade inside your upgrade. Each has its own compatibility story, maintainers and release cadence.
Toolchain coupling. A React Native bump can pull in new requirements for Xcode, the Android Gradle Plugin, the JDK or Node. These fail late, in CI, on someone else's machine.
Template drift. Your project's native files stopped matching the template years ago. A diff against a clean template can't know about your custom changes.
Architecture changes. Newer React Native versions change defaults (for example around the New Architecture). Libraries that never adopted the new model become blockers. Check the release notes of your target version for the current state.
Unknown unknowns. Abandoned packages, patched dependencies (patch-package) and forks.

A more honest estimate in four steps

Count native dependencies. The number matters more than total dependencies.
Classify each one: actively maintained / slow / abandoned, and "known compatible with the target version" / "unknown" / "known broken".
Do a time-boxed dry run on a throwaway branch: bump, install, build iOS and Android, record every failure. Stop after a fixed time (say a day).
Estimate from the dry run: your known failures plus a buffer proportional to the unknown count.

Give stakeholders a risk range, not a date

"Two weeks if three unknown dependencies behave, five if they don't" is more useful and more honest than a single number. It also tells your manager where the risk is.

What I'm building

I'm working on a tool, rn-upgrade-doctor, that automates steps 1 and 2 and produces a project-specific risk report. The CLI goes public on 20 Oct. If you want early access: [https://rnupgradedoctor.dev]

What was the worst upgrade estimate you ever got wrong? I'd love to hear it in the comments.