OtaKitFixing Capacitor version mismatch errors
Capacitor core, CLI, and plugins have to agree on a version. What triggers version mismatch errors, how to align @capacitor packages cleanly, and how it relates to your OTA runtime version.
Capacitor's core, CLI, and plugins are versioned together, and they don't appreciate being out of step. A mismatch shows up as build failures, runtime plugin errors, or a warning from npx cap doctor — and it's often the hidden cause behind errors that look like something else entirely. This guide covers how to spot and fix Capacitor version mismatches.
Start with the diagnosis command: npx cap doctor prints the installed Capacitor versions and flags mismatches. Run it first — it turns a guessing game into a checklist.
What has to agree
@capacitor/core,@capacitor/cli,@capacitor/ios,@capacitor/androidshould share the same major version.- Official plugins (
@capacitor/*) should target that same major. - Community plugins should declare compatibility with your Capacitor major.
Fix: align everything to one major
npx cap doctor # see the mismatch npm install @capacitor/core@latest @capacitor/cli@latest \ @capacitor/ios@latest @capacitor/android@latest npx cap sync
Then update your plugins to versions that support that major. If a community plugin has no compatible release, that's your blocker — and a candidate for replacement.
The native side
After aligning the npm packages, run npx cap sync so the native projects pick up the new versions. A mismatch that persists after sync usually means a plugin's native code is pinned to an incompatible SDK — check its docs for the required Capacitor version.
How this relates to OTA
Capacitor version alignment is a native concern, but it has an OTA parallel: your web bundle assumes a certain native runtime. OtaKit's runtime version is how you stop a bundle from reaching a native shell it's incompatible with — the same “these two have to agree” discipline, applied to over-the-air updates. See semantic versioning for bundles.
Pin your Capacitor versions in package.json rather than floating them. Surprise minor bumps from a loose range are a common way a working project starts throwing mismatch errors overnight.
Where to go next
See upgrading Capacitor 7 to 8 for a clean major bump and Android build errors for what mismatches often trigger downstream.