Skip to content
Capgo - Live Updates for Capacitor Apps Capgo

Common Update Problems

When an update check fails, Capgo usually returns an error code and a message in the /updates response. This page explains the most common failures and the fastest fixes.

Read this first

Section titled “Read this first”
  • no_new_version_available is a normal state, not a failure.
  • Many “update found but not applied” reports are policy/configuration refusals rather than cache lag, especially when the response includes an explicit error code.
  • Use npx @capgo/cli@latest app debug while reproducing the issue to see request/response details.

Common failure codes

Section titled “Common failure codes”

disable_auto_update_to_major

Section titled “disable_auto_update_to_major”

Cause

Your channel blocks major upgrades (disable_auto_update = major) and the target bundle major is above the device baseline version.

Typical symptom

version: 1.0.8 with old: 0.0.0 means the device reports baseline 0.0.0, so major upgrades are rejected.

How to interpret it

The backend compares major versions using device baseline old and target version.

  • If target is 1.0.1, baseline major must be 1 (for example 1.0.0).
  • If target is 10.0.1, baseline major must be 10 (for example 10.0.0).

Fix option A (recommended): align device baseline major

Set plugins.CapacitorUpdater.version in capacitor.config.* so its MAJOR matches the bundle MAJOR you want to deliver (for example 1.0.0 for 1.0.1, 10.0.0 for 10.0.1).

Then apply this config to the installed app once:

  1. Run npx cap sync.
  2. Rebuild and reinstall the native app.

Fix option B: relax channel policy

Allow cross-major auto-updates in channel settings (only if that rollout strategy is intentional).

Related docs:

disable_auto_update_to_minor / disable_auto_update_to_patch

Section titled “disable_auto_update_to_minor / disable_auto_update_to_patch”

Cause

Channel policy is stricter (minor or patch) than the update being offered.

Fix

  • Upload a bundle compatible with the current policy, or
  • change channel policy in dashboard/CLI.

Related docs:

disable_auto_update_to_metadata

Section titled “disable_auto_update_to_metadata”

Cause

Channel uses metadata-based targeting (version_number) and the device baseline is below required min_update_version.

Fix

  • Align device baseline (CapacitorUpdater.version) with installed native app version, or
  • adjust min_update_version / channel strategy.

Related docs:

disable_auto_update_under_native

Section titled “disable_auto_update_under_native”

Cause

Channel prevents downgrades below the native baseline.

Fix

  • Upload a bundle version greater than or equal to native baseline, or
  • disable “under native” downgrade protection for that channel.

Related docs:

cannot_update_via_private_channel

Section titled “cannot_update_via_private_channel”

Cause

Selected/default channel does not allow device self-assignment.

Fix

  • Use a different channel with self-assignment enabled, or
  • make the channel public / enable self-assignment.

Related docs:

unknown_version_build / semver_error

Section titled “unknown_version_build / semver_error”

Cause

Device baseline version is missing (unknown) or not valid semver.

Fix

  • Set plugins.CapacitorUpdater.version to a valid semver like 1.2.3.
  • Sync and rebuild native app.

Related docs:

unsupported_plugin_version

Section titled “unsupported_plugin_version”

Cause

Updater plugin version is too old for current backend requirements.

Fix

  • Upgrade @capgo/capacitor-updater.
  • Run npx cap sync.
  • Rebuild and reinstall native app.

disabled_platform_ios / disabled_platform_android

Section titled “disabled_platform_ios / disabled_platform_android”

Cause

Channel has updates disabled for that platform.

Fix

  • Enable platform toggle on the channel.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Section titled “disable_prod_build / disable_dev_build / disable_device / disable_emulator”

Cause

Channel disallows current build type or runtime target.

Fix

  • Align channel options (allow_prod, allow_dev, allow_device, allow_emulator) with your test target.

key_id_mismatch

Section titled “key_id_mismatch”

Cause

Bundle encryption key and device key differ.

Fix

  • Use the same encryption key/public key across app config and bundle encryption workflow.

no_channel / null_channel_data

Section titled “no_channel / null_channel_data”

Cause

No valid channel was resolved for the device.

Fix

  • Set a cloud default channel, or
  • set defaultChannel in test builds, or
  • assign channel override for device.

Related docs:

on_premise_app

Section titled “on_premise_app”

Cause

The backend returned HTTP 429 with on_premise_app. This happens in three situations:

  1. App ID does not exist in Capgo — the app_id sent by the device is not registered, so the backend has no record of it.
  2. App is flagged as on-premise — the app exists but is configured for self-hosted updates, so the Capgo cloud endpoint refuses to serve it.
  3. Organization plan is cancelled — the app’s organization no longer has an active subscription.

Common mistake

A typo in plugins.CapacitorUpdater.appId (in capacitor.config.ts) or a mismatch with the app ID registered in the Capgo dashboard. The backend cannot distinguish “unknown app” from “on-premise app”, so it returns the same error code.

Fix

  • Verify the app_id matches exactly what is shown in the Capgo dashboard (case-sensitive).
  • If the app is not registered yet, run npx @capgo/cli@latest app add.
  • If the app is intentionally on-premise, set plugins.CapacitorUpdater.updateUrl to your self-hosted update endpoint instead of the Capgo cloud URL.
  • If the organization plan expired, renew or upgrade the plan.

Quick diagnostic checklist

Section titled “Quick diagnostic checklist”
  1. Confirm app ID and channel are correct for the build.
  2. Confirm CapacitorUpdater.version matches installed native app version.
  3. Confirm channel policy (disable_auto_update) matches intended rollout.
  4. Confirm platform/build target toggles allow this device.
  5. Run npx @capgo/cli@latest app debug and read backend error code.

Need more help?

Section titled “Need more help?”

Keep going from Common Update Problems

Section titled “Keep going from Common Update Problems”

If you are using Common Update Problems to plan native plugin work, connect it with Using @capgo/capacitor-updater for the native capability in Using @capgo/capacitor-updater, Capgo Plugin Directory for the product workflow in Capgo Plugin Directory, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Plugins for the implementation detail in Adding or Updating Plugins, and Ionic Enterprise Plugin Alternatives for the product workflow in Ionic Enterprise Plugin Alternatives.