Problemi comuni di aggiornamento

When an update check fails, Capgo usually returns an error code e un message nel /updates risposta. Questa pagina spiega i fallimenti più comuni e le correzioni più rapide.

Leggi prima questo

• no_new_version_available è uno stato normale, non un errore.
• Molti report “update found but not applied” sono rifiuti di policy/configurazione e non lag di cache, soprattutto quando la risposta include un esplicito error code.
• Usa npx @capgo/cli@latest app debug durante la riproduzione del problema per visualizzare i dettagli di richiesta/risposta.

Codici di errore comuni

provider_infrastructure_request_blocked

Causa

L'app ha Blocca le richieste all'infrastruttura del provider abilitato e la richiesta proviene da un intervallo di IP di un datacenter Google o Apple noto. Capgo blocca queste richieste su /updates, /stats, e /channel_self per evitare che il traffico proveniente dal provider venga considerato traffico del dispositivo.

Soluzione

• Riproduci l'aggiornamento da un dispositivo fisico su una rete utente standard.
• Non usare probe cloud o runner nei datacenter dei provider per i controlli di updater, stats o channel-self con questa protezione attiva.
• Se quel traffico è intenzionale, apri la scheda Informazioni della tua app e disattiva Blocca le richieste all'infrastruttura del provider. Riattivala una volta terminato il test.

Le nuove app hanno questa protezione attiva di default. Le app create prima dell'introduzione dell'impostazione la mantengono disattivata finché non la attivi tu.

Dettagli della risposta

• /updates mantiene il contratto di risposta dell'updater e restituisce HTTP 200. Il suo corpo include error, message, kind: "blocked", e provider ("google" oppure "apple").
• /stats e /channel_self restituisce HTTP 429 con lo stesso errore code. Tratta questo come un blocco di policy intenzionale, non come una condizione di retry transitoria.

disable_auto_update_to_major

Causa

Il tuo canale blocca gli upgrade major (disable_auto_update = major) e la major del bundle di destinazione è superiore alla versione di baseline del dispositivo.

Sintomo tipico

version: 1.0.8 con old: 0.0.0 significa che il dispositivo riporta una baseline 0.0.0, quindi gli upgrade major vengono rifiutati.

Come interpretarlo

Il backend confronta le versioni major usando la baseline del dispositivo old e il target version.

• Se il target è 1.0.1, la major della baseline deve essere 1 (ad esempio 1.0.0).
• Se il target è 10.0.1, la major della baseline deve essere 10 (ad esempio 10.0.0).

Soluzione A (consigliata): allinea la major della baseline del dispositivo

Imposta plugins.CapacitorUpdater.version nella capacitor.config.* quindi è MAJOR corrisponde alla versione MAJOR del bundle che vuoi distribuire (ad esempio 1.0.0 per 1.0.1, 10.0.0 per 10.0.1).

Quindi applica questa configurazione all'app installata una sola volta:

1. Esegui npx cap sync.
2. Ricostruisci e reinstalla l'app nativa.

Soluzione B: allenta la policy del canale

Consenti aggiornamenti automatici cross-major nelle impostazioni del canale (solo se questa strategia di rollout è intenzionale).

Documentazione correlata:

• Version Targeting: disabilitare l'auto-update tra versioni major
• Canali: strategie per disabilitare l'auto-update

disable_auto_update_to_minor / disable_auto_update_to_patch

Causa

La policy del canale è più restrittiva (minor oppure patch) rispetto all'update offerto.

• minor blocca se il bundle di destinazione ha una major o minor diversa dalla baseline nativa del dispositivo (version_build). Esempio: 1.2.3 -> 1.3.0 è bloccato.
• patch blocca qualsiasi modifica al numero major, minor o patch da version_build. Sono consentiti solo cambi di suffisso mentre MAJOR.MINOR.PATCH rimane identico, ad esempio 1.0.0-beta.1 -> 1.0.0-beta.2 oppure 1.0.0+build.1 -> 1.0.0+build.2.

Soluzione

• Carica un bundle compatibile con la policy corrente, oppure
• modifica la policy del canale in dashboard/CLI.

Documentazione correlata:

• Canali: strategie per disabilitare l'auto-update

disable_auto_update_to_metadata

Causa

Il canale usa targeting basato su metadati (version_number) e la baseline del dispositivo è inferiore al requisito min_update_version.

Soluzione

• Allinea la baseline del dispositivo (CapacitorUpdater.version) alla versione dell'app nativa installata, oppure
• regola min_update_version la strategia del canale.

Documentazione correlata:

• Canali: strategie per disabilitare l'auto-update

disable_auto_update_under_native

Causa

Il canale impedisce i downgrade sotto la baseline nativa.

Soluzione

• Carica una versione del bundle maggiore o uguale alla baseline nativa, oppure
• disabilita la protezione dai downgrade “under native” per quel canale.

Documentazione correlata:

• Version Targeting: prevenzione del downgrade automatico

cannot_update_via_private_channel

Causa

Il canale selezionato/predefinito non consente l'auto-assegnazione del dispositivo.

Soluzione

• Usa un canale diverso con auto-assegnazione abilitata, oppure
• rendi il canale pubblico / abilita l'auto-assegnazione.

Documentazione correlata:

• Canali: utilizzo di setChannel() dalla tua app

unknown_version_build / semver_error

Causa

Manca la versione baseline del dispositivo (unknown) o non è un semver valido.

Soluzione

• Imposta plugins.CapacitorUpdater.version per un un semver valido come 1.2.3.
• Sincronizza e ricostruisci l'app nativa.

Documentazione correlata:

• Canali: versioning dei bundle e canali
• Troubleshooting: aggiornamenti non applicati

unsupported_plugin_version

Causa

La versione del plugin Updater è troppo vecchia per i requisiti attuali del backend.

Soluzione

• Aggiorna @capgo/capacitor-updater.
• Esegui npx cap sync.
• Ricompila e reinstalla l'app nativa.

disabled_platform_ios / disabled_platform_android

Causa

Il canale ha gli aggiornamenti disabilitati per quella piattaforma.

Soluzione

• Abilita il toggle della piattaforma sul canale.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Causa

Il canale non consente il tipo di build o il runtime target corrente.

Soluzione

• Allinea le opzioni del canale (allow_prod, allow_dev, allow_device, allow_emulator) con il tuo target di test.

key_id_mismatch

Causa

Le chiavi di cifratura del bundle e del dispositivo differiscono.

Soluzione

• Usa la stessa chiave di cifratura/chiave pubblica nella config dell'app e nel workflow di cifratura bundle.

no_channel / null_channel_data

Causa

Nessun canale valido è stato determinato per il dispositivo.

Soluzione

• Imposta un canale cloud predefinito, oppure
• imposta defaultChannel nelle build di test, oppure
• assegna un channel override al dispositivo.

Documentazione correlata:

• Canali

on_premise_app

Causa

Il backend ha restituito HTTP 429 con on_premise_app. Questo accade in tre situazioni:

1. L'App ID non esiste in Capgo — l'ID app_id inviato dal dispositivo non è registrato, quindi il backend non ne ha traccia.
2. L'app è contrassegnata come on-premise — l'app esiste ma è configurata per aggiornamenti self-hosted, quindi l'endpoint cloud di Capgo rifiuta di servirla.
3. Il piano dell'organizzazione è stato annullato — l'organizzazione dell'app non ha più un abbonamento attivo.

Errore comune

Un refuso in plugins.CapacitorUpdater.appId (in capacitor.config.ts) o una discrepanza con l'App ID registrato nella dashboard di Capgo. Il backend non può distinguere tra “app sconosciuta” e “app on-premise”, quindi restituisce lo stesso errore code.

Soluzione

• Verifica il app_id corrisponde esattamente a quanto mostrato nella dashboard di Capgo (distingue tra maiuscole e minuscole).
• Se l'app non è ancora registrata, esegui npx @capgo/cli@latest app add.
• Se l'app è intenzionalmente on-premise, imposta plugins.CapacitorUpdater.updateUrl sul tuo endpoint di aggiornamento self-hosted al posto dell'URL cloud di Capgo.
• Se il piano dell'organizzazione è scaduto, rinnova o passa a un piano superiore.

Checklist diagnostica rapida

1. Verifica che l'app ID e il canale siano corretti per il build.
2. Verifica CapacitorUpdater.version corrisponde alla versione dell'app nativa installata.
3. Verifica che la policy del canale (disable_auto_update) corrisponda al rollout previsto.
4. Verifica che i toggle platform/build target permettano l'uso su questo dispositivo.
5. Esegui npx @capgo/cli@latest app debug e leggi l'errore del backend code.

Ti serve altro aiuto?

• Risoluzione problemi
• Come ricevere supporto

Continua da Problemi comuni di aggiornamento

Se stai usando Problemi comuni di aggiornamento per pianificare il lavoro sui plugin nativi, collegalo a Usando @capgo/capacitor-updater per la funzionalità nativa in Usando @capgo/capacitor-updater, Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli su come aggiungere o aggiornare i plugin, e Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin Ionic Enterprise.