Problemi di Aggiornamento Comuni

Quando un controllo di aggiornamento fallisce, Capgo di solito restituisce 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 un fallimento.
• Molti rapporti di “aggiornamento trovato ma non applicato” sono rifiuti di politica/configurazione piuttosto che ritardi di cache, soprattutto quando la risposta include un’espressione esplicita error code.
• Usa npx @capgo/cli@latest app debug mentre si riproduce il problema per visualizzare i dettagli della richiesta/risposta.

Codici di fallimento comuni

disable_auto_update_to_major

Causa

Il tuo canale blocca gli aggiornamenti di versione maggiore (disable_auto_update = majore il bundle principale 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 principali vengono rifiutati.

Come interpretarlo

Il backend confronta le versioni principali utilizzando la versione di base del dispositivo old e di destinazione version.

• Se di destinazione è 1.0.1, la versione di base principale deve essere 1 (ad esempio 1.0.0).
• Se di destinazione è 10.0.1baseline maggiore deve essere 10 (ad esempio 10.0.0).

Opzione di correzione A (consigliata): allinea il baseline maggiore del dispositivo

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

Poi applica 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 inter-major nel menu impostazioni del canale (solo se quella strategia di distribuzione è intenzionale).

Documenti correlati:

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

disable_auto_update_to_minor / disable_auto_update_to_patch

Causa

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

• minor blocca quando il pacchetto di destinazione ha un numero maggiore o minore della versione nativa del dispositivo (baseline)version_buildEsempio: 1.2.3 -> 1.3.0 è bloccato.
• patch blocca qualsiasi cambiamento di versione maggiore, minore o di patch da version_build. Sono consentiti solo cambiamenti di suffisso mentre MAJOR.MINOR.PATCH rimane identico, ad esempio 1.0.0-beta.1 -> 1.0.0-beta.2 o 1.0.0+build.1 -> 1.0.0+build.2.

Risolvi

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

Documentazione correlata:

• Canali: Disabilita strategie di aggiornamento automatico

disable_auto_update_to_metadata

Motivo

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

Risoluzione

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

Documenti correlati:

• Canali: Disabilita le strategie di aggiornamento automatico

disable_auto_update_under_native

Motivo

Prevenire la discesa di canale sotto la base nativa.

Risoluzione

• Carica una versione del pacchetto maggiore o uguale alla base nativa, o
• disabilita la protezione della discesa 'sotto la base nativa' per quel canale.

Documenti correlati:

• Target di versione: Prevenzione della discesa automatica

cannot_update_via_private_channel

Causa

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

Risoluzione

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

Documenti correlati:

• Canali: Utilizzo di setChannel() dal tuo App

unknown_version_build / semver_error

Causa

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

Risoluzione

• Imposta plugins.CapacitorUpdater.version a una valida semver come ad esempio 1.2.3.
• Riassembla e ricostruisci l'app nativa.

Documenti correlati:

• Canali: Gestione delle versioni del pacchetto e canali
• Risoluzione dei problemi: Aggiornamenti non applicati

unsupported_plugin_version

Causa

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

Soluzione

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

disabled_platform_ios / disabled_platform_android

Problema

Questo canale ha le aggiornamenti disabilitati per quella piattaforma.

Risoluzione

• Abilita il pulsante di piattaforma sul canale.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Problema

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

Problema

Le chiavi di crittografia del bundle e la chiave del dispositivo differiscono.

Risolvi

• Usa la stessa chiave di crittografia/chiave pubblica in entrambi i flussi di configurazione dell'app e crittografia del bundle.

no_channel / null_channel_data

Causa

Non è stato risolto alcun canale valido per il dispositivo.

Risolvi

• Imposta un canale di rete predefinito, o
• imposta defaultChannel in costruzioni di test, o
• assegna un sovrascrittura del canale per dispositivo.

Documentazione correlata:

• Canali

on_premise_app

Causa

Il backend ha restituito HTTP 429 con on_premise_appCiò accade in tre situazioni:

1. L'ID dell'app non esiste in Capgo — il app_id inviato dal dispositivo non è registrato, quindi il backend non ne ha alcun record.
2. L'app è segnalata come on-premise — l'app esiste ma è configurata per aggiornamenti self-hosted, quindi il cloud endpoint 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 battitura in plugins.CapacitorUpdater.appId (in capacitor.config.ts) o una disallineamento con l'ID dell'app registrata nel dashboard Capgo . Il backend non può distinguere l' 'applicazione sconosciuta' dall' 'applicazione on-premise', quindi restituisce lo stesso errore code.

Correzione

• Verifica che app_id corrisponda esattamente a quanto mostrato nel dashboard Capgo (con sensibilità di caso).
• Se l'app non è registrata ancora, esegui npx @capgo/cli@latest app add.
• Se l'app è intenzionalmente on-premise, impostare plugins.CapacitorUpdater.updateUrl a tuo endpoint di aggiornamento auto-hosted al posto dell'URL cloud Capgo.
• Se il piano di organizzazione è scaduto, rinnova o aggiorna il piano.

Elenco diagnostico rapido

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

Hai bisogno di ulteriore aiuto?

• Risoluzione dei problemi
• Come ottenere supporto

Continua da Problemi di Aggiornamento Comuni

Se stai utilizzando Problemi di Aggiornamento Comuni per pianificare il lavoro di plugin nativo, connettilo con Utilizzare @capgo/capacitor-aggiornatore per la capacità nativa in Utilizzare @capgo/capacitor-aggiornatore, Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin, Capacitor Plugin da Capgo per il dettaglio di implementazione in Capacitor Plugin da Capgo Aggiunta o Aggiornamento Plugin per la descrizione dettagliata in Aggiunta o Aggiornamento Plugin, e Alternative Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Alternative Plugin Enterprise Ionic.