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

• 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

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:

• Version Targeting: Disable Auto-Update Across Major Versions
• Channels: Disable Auto Update strategies

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:

• Channels: Disable Auto Update strategies

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:

• Channels: Disable Auto Update strategies

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:

• Version Targeting: Auto-Downgrade Prevention

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:

• Channels: Using setChannel() from Your App

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:

• Channels: Bundle Versioning and Channels
• Troubleshooting: Updates not applying

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

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

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

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

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:

• Channels

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

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?

• Troubleshooting
• How to get support