Problemi di Aggiornamento Comuni

Quando un controllo di aggiornamento fallisce, Capgo restituisce generalmente 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 esplicito 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 dispositivo baseline maggiore

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).

Quindi applica questa configurazione all'applicazione installata una volta:

1. Esegui 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 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.

Soluzione

• 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

Causa

Il canale utilizza la targeting basata 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 Strategia del canale.

Documenti correlati:

• Canali: Disabilita strategie di aggiornamento automatico

disable_auto_update_under_native

Causa

Il canale impedisce le riduzioni di versione al di sotto del baseline nativo.

Risoluzione

• Carica una versione del pacchetto maggiore o uguale al baseline nativo, o
• disabilita la protezione dalla riduzione di versione “sotto nativo” per quel canale.

Documenti correlati:

• Versione di destinazione: Prevenzione del downgrade automatico

cannot_update_via_private_channel

Problema

La canale selezionata/impiegata non consente l'assegnazione automatica del dispositivo.

Risoluzione

• Usa una canale diversa che consente l'assegnazione automatica del dispositivo, o
• rendi la canale pubblica / abilita l'assegnazione automatica del dispositivo.

Documentazione correlata:

• Canali: Utilizzo di setChannel() dal tuo App

unknown_version_build / semver_error

Problema

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

Ripara

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

Documentazione correlata:

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

unsupported_plugin_version

Causa

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

Risolvi

• 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.

Risolvi

• Abilita il pulsante di abilitazione della piattaforma sul canale.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Causa

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

Risolvi

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

key_id_mismatch

Causa

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

Risolvi

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

no_channel / null_channel_data

Causa

Non è stato risolto alcun canale valido per il dispositivo.

Risolvi

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

Mistake comune

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

Correzione

• Verifica che app_id corrisponda esattamente a quanto mostrato nel dashboard Capgo (senza distinzione tra maiuscole e minuscole).
• 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 impostare il tuo endpoint di aggiornamento auto-hosted al posto dell'URL cloud Capgo.
• If the organization plan expired, renew or upgrade the plan.

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 i pulsanti di toggling della piattaforma/obiettivo di build consentono a questo dispositivo.
5. Esegui e leggi l'errore del backend __CAPGO_KEEP_0__. npx @capgo/cli@latest app debug and read backend error code.

Sottosezione intitolata “Hai bisogno di più aiuto?”

• Come ottenere supporto
• Continua da Problemi di aggiornamento comuni

Sottosezione intitolata “Continua da Problemi di aggiornamento comuni”

Problemi di aggiornamento comuni per pianificare il lavoro dei plugin nativi, connettilo con Utilizzando @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-aggiornatore Using @capgo/capacitor-updater per la capacità nativa in Utilizzo di @capgo/capacitor-aggiornatore, Capgo Directory Plugin per il flusso di lavoro del prodotto in Capgo Directory Plugin, Capacitor Plugin da Capgo per il dettaglio di implementazione in Capacitor Plugin da Capgo, Aggiunta o Aggiornamento di Plugin per il dettaglio di implementazione in Aggiunta o Aggiornamento di Plugin, e Alternative per Plugin di Impresa Ionic per il flusso di lavoro del prodotto in Alternative per Plugin di Impresa Ionic.