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

provider_infrastructure_request_blocked

Causa

L'applicazione ha Blocca le richieste di infrastruttura del provider enabled and the request originated from a known Google or Apple datacenter IP range. Capgo blocks these requests on /updates, /stats__CAPGO_KEEP_0__ blocca queste richieste su /channel_self e

per prevenire il traffico originato dal provider dal essere trattato come traffico di dispositivo.

• Risolvi
• Riproduci l'aggiornamento da un dispositivo fisico su una rete di utente normale.
• Non utilizzare probe ospitati in cloud o esecutori di datacenter del provider per aggiornamenti, statistiche o controlli di canale-self mentre questa protezione è abilitata. Se quel traffico è intenzionale, apri la scheda Informazioni e disabilitaBlocca le richieste di infrastruttura del provider",". Riabilita quando il test è completo.

Le nuove app hanno questa protezione abilitata per impostazione predefinita. Le app create prima dell'introduzione della impostazione hanno la protezione disabilitata fino a quando non l'abilitate.

Dettagli della risposta

• /updates preserva il contratto di risposta dell'aggiornatore e restituisce HTTP 200 Il suo corpo include error, message, kind: "blocked", e provider ("google" o "apple").
• /stats e /channel_self ritorna HTTP 429 con lo stesso errore code. Considera questo come una politica di blocco intenzionale, non come una condizione di riprova transitoria.

disable_auto_update_to_major

Causa

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

Come interpretarlo

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

• Se target è 1.0.1, la versione di base maggiore deve essere 1 (ad esempio 1.0.0).
• Se target è 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 suo 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 gli aggiornamenti automatici inter-major nel pannello di configurazione dei canali (solo se questa strategia di rilascio è intenzionale).

Documenti correlati:

• 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) dell'aggiornamento offerto.

• minor blocca quando il pacchetto di destinazione ha un numero maggiore o minore della versione nativa del dispositivo (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, come 1.0.0-beta.1 -> 1.0.0-beta.2 o 1.0.0+build.1 -> 1.0.0+build.2.

Fix

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

Documenti correlati:

• Canali: Disabilita strategie di aggiornamento automatico

disable_auto_update_to_metadata

Causa

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

Risoluzione

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

Documentazione correlata:

• Canali: Disabilita le strategie di aggiornamento automatico

disable_auto_update_under_native

Causa

Il canale impedisce le riduzioni sotto la base di riferimento nativa.

Risoluzione

• Carica una versione del pacchetto maggiore o uguale alla base di riferimento nativa, o
• disabilita la protezione contro le riduzioni 'sotto la base nativa' per quel canale.

Documentazione correlata:

• Versione di destinazione: Prevenzione automatica delle riduzioni

cannot_update_via_private_channel

Causa

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

Risoluzione

• Utilizza un canale diverso con l'assegnazione automatica abilitata, o
• rendi il canale pubblico / abilita l'assegnazione automatica.

Documenti correlati:

• Canali: Utilizzo di 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 valida semver come 1.2.3.
• Riassembla e ricostruisci l'app nativa.

Documenti correlati:

• Canali: Gestione delle versioni del pacchetto e canali
• Risolvere 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 toggling della piattaforma sul canale.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Problema

Il canale non consente il tipo di build 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

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

Risoluzione

• Usare la stessa chiave di crittografia/chia pubblica all'interno della configurazione dell'app e del flusso di crittografia del bundle.

no_channel / null_channel_data

Causa

Non è stato risolto alcun canale valido per il dispositivo.

Risoluzione

• Impostare un canale di rete predefinito, o
• impostare defaultChannel in costruzioni di test, o
• asignare un override del canale per dispositivo.

Documentazione correlata:

• Canali

on_premise_app

Causa

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

1. L'ID dell'app non esiste in Capgo — il app_id invio effettuato 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'appartenente all'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 è ancora registrata, esegui npx @capgo/cli@latest app add.
• Se l'app è intenzionalmente on-premise, impostare plugins.CapacitorUpdater.updateUrl al tuo endpoint di aggiornamento auto-hosted al posto dell'URL cloud Capgo.
• Se il piano di organizzazione è scaduto, rinnova o aggiorna il piano.

Elenco di controllo diagnostico rapido

1. Conferma che l'ID dell'app e il canale siano corretti per la build.
2. Conferma CapacitorUpdater.version corrisponde alla versione dell'app nativa installata.
3. Conferma che la politica del canale (disable_auto_update) corrisponda alla distribuzione prevista.
4. Conferma che i pulsanti di toggling piattaforma/build consentano 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 Utilizzando @capgo/capacitor-aggiornatore per la capacità nativa in Utilizzando @capgo/capacitor-aggiornatore, Capgo Directory dei Plugin per il flusso di lavoro del prodotto in Capgo Directory dei Plugin, Capacitor Plugin da Capgo per la dettaglio di implementazione in Capacitor Plugin da Capgo Aggiunta o Aggiornamento Plugin per la dettagliata implementazione in Aggiunta o Aggiornamento Plugin, e Alternative Plugin per Enterprise Ionic per il flusso di lavoro del prodotto in Alternative Plugin per Enterprise Ionic.