Problemi di aggiornamento comuni

Quando il controllo delle aggiornamenti fallisce, Capgo restituisce di solito un error code e un message nel /updates risposta. Questa pagina spiega le più comuni fallite e le soluzioni più veloci.

Leggi questo prima

• no_new_version_available è uno stato normale, non una fallita.
• Molti rapporti di “aggiornamento trovato ma non applicato” sono rifiuti di politica/configurazione piuttosto che ritardi di cache, specialmente quando la risposta include un error code esplicito.
• Usa npx @capgo/cli@latest app debug mentre si riproduce l'errore per visualizzare i dettagli della richiesta/risposta.

Codici di errore comuni

disable_auto_update_to_major

Causa

Il tuo canale blocca gli aggiornamenti a versione maggiore (disable_auto_update = major) e la versione maggiore del pacchetto di destinazione è superiore alla versione di base del dispositivo.

Sintomo tipico

version: 1.0.8 con old: 0.0.0 significa che il dispositivo segnala la versione di base 0.0.0, quindi gli aggiornamenti a versione maggiore vengono rifiutati.

Come interpretarlo

Il backend confronta le versioni maggiori utilizzando il dispositivo di riferimento old e target version.

• Se target è 1.0.1la versione maggiore del dispositivo di riferimento deve essere 1 (ad esempio 1.0.0).
• Se target è 10.0.1la versione maggiore del dispositivo di riferimento deve essere 10 (ad esempio 10.0.0).

Opzione di correzione A (consigliata): allinea la versione maggiore del dispositivo di riferimento

Imposta plugins.CapacitorUpdater.version in capacitor.config.* così che sia MAJOR corrisponde al bundle MAJOR che desideri distribuire (ad esempio 1.0.0 per 1.0.1, 10.0.0 per 10.0.1).

Applica quindi questa configurazione all'applicazione installata una volta:

1. Eseguisci npx cap sync.
2. Riavvia e reinstalla l'app nativa.

Opzione B: rilassa la politica del canale

Consenti aggiornamenti automatici intermajor nei impostazioni del canale (solo se questa strategia di distribuzione è intenzionale).

Documentazione correlata:

• Target di versione: Disabilita l'aggiornamento automatico tra versioni maggiori
• Canali: Disabilita le strategie di aggiornamento automatico

disable_auto_update_to_minor / disable_auto_update_to_patch

Causa

La politica del canale è più restrittiva (minor o patch) rispetto all'aggiornamento offerto.

Risoluzione

• Carica un bundle compatibile con la politica corrente, o
• modifica la politica del canale nel dashboard/CLI.

Documentazione correlata:

• Canali: strategie per disabilitare l'aggiornamento automatico

disable_auto_update_to_metadata

Causa

Il canale utilizza la targeting basato sui metadati (version_number) e il livello di dispositivo è inferiore a quello richiesto min_update_version.

Risolvi

• Allinea il livello di dispositivo (CapacitorUpdater.version) con la versione nativa dell'app installata, o
• adatta min_update_version / strategia del canale.

Documenti correlati:

• Canali: Disabilita strategie di aggiornamento automatico

disable_auto_update_under_native

Causa

Il canale impedisce le riduzioni di versione sotto il livello di dispositivo nativo.

Risolvi

• Carica una versione del pacchetto maggiore o uguale alla baseline nativa, o
• disabilita la protezione del downgrade "sotto nativo" per quel canale.

Documentazione correlata:

• Versione di destinazione: Prevenzione del downgrade automatico

cannot_update_via_private_channel

Causa

Il canale selezionato/predefinito non consente l'assegnazione del dispositivo da parte dell'utente.

Risolvi

• Usa un canale diverso con l'assegnazione del dispositivo abilitata, o
• rendi pubblico il canale / abilita l'assegnazione del dispositivo.

Documentazione correlata:

• Canali: Utilizza setChannel() dal tuo App

unknown_version_build / semver_error

Causa

La versione di base del dispositivo manca (unknown) o non è valida semver.

Risoluzione

• Imposta plugins.CapacitorUpdater.version a una versione semver valida come 1.2.3.
• Sincronizza e ricostruisci l'app nativa.

Documentazione correlata:

• Canali: Bundle Versioning e Canali
• Risoluzione dei problemi: Aggiornamenti non applicati

unsupported_plugin_version

Causa

La versione del plugin aggiornatore è troppo vecchia per le richieste attuali del backend.

Soluzione

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

disabled_platform_ios / disabled_platform_android

Causa

Il canale ha le aggiornamenti disabilitati per quella piattaforma.

Soluzione

• Abilita il pulsante di selezione della piattaforma sul canale.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Causa

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

Risoluzione

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

key_id_mismatch

Causa

La chiave di crittografia del pacchetto e la chiave del dispositivo differiscono.

Risoluzione

• Utilizza la stessa chiave di crittografia/chiaave pubblica in tutta la configurazione dell'app e nel flusso di crittografia del pacchetto.

no_channel / null_channel_data

Causa

Non è stato risolto alcun canale valido per il dispositivo.

Risolvi

• Imposta un canale di default cloud, o
• imposta defaultChannel in costruzioni di test, o
• assegna override del canale per 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'ID dell'app non esiste in Capgo — il app_id invia il dispositivo non è registrato, quindi il backend non ha alcun record di esso.
2. L'app è segnalata come on-premise — l'app esiste ma è configurata per aggiornamenti self-hosted, quindi l'endpoint cloud di Capgo rifiuta di servirla.
3. Il piano di organizzazione è stato annullato — l'app dell'organizzazione non ha più una sottoscrizione attiva.

Errore comune

Un errore di ortografia in plugins.CapacitorUpdater.appId (in capacitor.config.ts) o una disallineazione con l'ID dell'app registrato nel dashboard di Capgo. Il backend non può distinguere “app sconosciuta” da “app on-premise”, quindi restituisce lo stesso errore code.

Risolvi

• Verifica che corrisponda esattamente a quanto mostrato nel dashboard __CAPGO_KEEP_0__ (senza distinzione tra maiuscole e minuscole). app_id matches exactly what is shown in the Capgo dashboard (case-sensitive).
• Se l'app è intenzionalmente in locale, imposta npx @capgo/cli@latest app add.
• al tuo endpoint di aggiornamento auto-hosted al posto dell'URL Cloudflare __CAPGO_KEEP_0__. plugins.CapacitorUpdater.updateUrl to your self-hosted update endpoint instead of the Capgo cloud URL.
• Elenco di controllo rapido diagnostico

Sezione intitolata “Elenco di controllo rapido diagnostico”

1. Conferma
2. corrisponde alla versione dell'app nativa installata. CapacitorUpdater.version Risolvi
3. Conferma la politica del canale (disable_auto_update) corrisponde alla distribuzione prevista.
4. Conferma che le impostazioni di piattaforma/compilazione consentono questo dispositivo.
5. Esegui npx @capgo/cli@latest app debug e leggi gli errori di backend code.

Hai bisogno di più aiuto?

• Risoluzione dei problemi
• Come ottenere supporto