Masalah Pembaharuan Umum

Ketika cek update gagal, Capgo biasanya mengembalikan sebuah error code dan sebuah message dalam /updates respons. Halaman ini menjelaskan gagal umum dan perbaikan tercepat.

Baca terlebih dahulu

• no_new_version_available adalah keadaan normal, bukan kegagalan.
• Banyak laporan “ditemukan tetapi tidak diterapkan” yang merupakan penolakan kebijakan/konfigurasi daripada keterlambatan cache, terutama ketika respons mencakup instruksi error code.
• Gunakan npx @capgo/cli@latest app debug sambil mereproduksi masalah untuk melihat detail permintaan/respon.

Kode kegagalan umum

provider_infrastructure_request_blocked

Penyebab

Aplikasi memiliki Mencegah permintaan infrastruktur penyedia enabled and the request originated from a known Google or Apple datacenter IP range. Capgo blocks these requests on /updates, /stats__CAPGO_KEEP_0__ mencegah permintaan ini di /channel_self , dan

untuk mencegah lalu lintas asal penyedia dari dianggap sebagai lalu lintas perangkat.

• Perbaiki
• Reproduksi update dari perangkat fisik di jaringan pengguna normal.
• Jangan menggunakan probe yang di-host di awan atau pengguna datacenter penyedia untuk pembaruan, statistik, atau pengecekan saluran-self sementara proteksi ini diaktifkan. Jika lalu lintas itu sengaja, buka tab Informasi dan matikanMencegah permintaan infrastruktur penyedia

Apps baru memiliki perlindungan ini diaktifkan secara default. Aplikasi yang dibuat sebelum pengaturan diperkenalkan tetap dinonaktifkan sampai Anda mengaktifkannya.

Detail Respon

• /updates mengembalikan kontrak respon pembaruan dan mengembalikan HTTP 200 dengan isi tubuhnya yang mencakup error, message, kind: "blocked", dan provider ("google" atau "apple").
• /stats mengembalikan HTTP /channel_self dengan kesalahan yang sama __CAPGO_KEEP_0__. Lihat ini sebagai kebijakan pemblokiran sengaja, bukan kondisi ulang coba. 429 with the same error code. Treat this as an intentional policy block, not a transient retry condition.

disable_auto_update_to_major

Saluran Anda memblokir pembaruan besar (

Channel Anda memblokir pembaruan besar (disable_auto_update = majordan versi utama bundle target lebih tinggi dari versi dasar perangkat.

Gejala biasa

version: 1.0.8 dengan old: 0.0.0 berarti perangkat melaporkan versi dasar 0.0.0, sehingga pembaruan utama ditolak.

Bagaimana cara memahami hal ini

Backend membandingkan versi utama menggunakan versi dasar perangkat old dan target version.

• Jika target adalah 1.0.1, versi dasar utama harus 1 (contoh 1.0.0).
• Jika target adalah 10.0.1basis utama harusnya 10 (misalnya 10.0.0).

Pilih opsi A (direkomendasikan): sesuaikan basis utama perangkat

Set plugins.CapacitorUpdater.version di capacitor.config.* jadi MAJOR sama dengan bundle MAJOR yang ingin Anda kirim (misalnya 1.0.0 untuk 1.0.1, 10.0.0 untuk 10.0.1).

Lalu terapkan konfigurasi ini ke aplikasi yang sudah terpasang sekali:

1. Jalankan npx cap sync.
2. Rebuild dan instal ulang aplikasi native.

Atur opsi B: lembagakan kebijakan saluran

Izinkan pembaruan otomatis lintas-maor di pengaturan saluran (hanya jika strategi perluasan itu sengaja).

Dokumen terkait:

• Target Versi: Nonaktifkan Pembaruan Otomatis di Antara Versi Utama
• Saluran: Nonaktifkan Strategi Pembaruan Otomatis

disable_auto_update_to_minor / disable_auto_update_to_patch

Penyebab

Kebijakan saluran lebih ketat (atau) daripada pembaruan yang ditawarkan.minor menghalangi ketika bundle target memiliki versi utama atau minor yang berbeda dengan dasar native perangkat ( patchatau

• minor )version_buildContoh: 1.2.3 -> 1.3.0 Diblokir.
• patch menghalangi perubahan nomor mayor, minor, atau patch apa pun dari version_build. Hanya perubahan sufiks yang diizinkan sementara MAJOR.MINOR.PATCH tetap identik, seperti 1.0.0-beta.1 -> 1.0.0-beta.2 atau 1.0.0+build.1 -> 1.0.0+build.2.

Perbaiki

• Unggah bundle yang kompatibel dengan kebijakan saat ini, atau
• ubah kebijakan saluran di dashboard/CLI.

Dokumen terkait:

• Saluran: Nonaktifkan Strategi Auto Update

disable_auto_update_to_metadata

Penyebab

Saluran menggunakan target berdasarkan metadata (version_number) dan garis dasar perangkat di bawah yang dibutuhkan min_update_version.

Pemecahan Masalah

• Sinkronkan garis dasar perangkat (CapacitorUpdater.version) dengan versi aplikasi native yang terpasang, atau
• Penyesuaian min_update_version / strategi saluran.

Referensi Dokumen:

• Saluran: Matikan Strategi Auto Update

disable_auto_update_under_native

Penyebab

Saluran mencegah penurunan di bawah dasar garis native.

Fix

• Unggah versi bundle yang sama atau lebih besar dari dasar garis native, atau
• nonaktifkan perlindungan penurunan di bawah native untuk saluran tersebut.

Dokumen terkait:

• Target Versi: Pencegahan Penurunan Otomatis

cannot_update_via_private_channel

Penyebab

Saluran yang dipilih/default tidak memungkinkan pengasasan perangkat sendiri.

Fix

• Gunakan saluran yang berbeda dengan pengasasan perangkat diaktifkan, atau
• buat saluran publik / diaktifkan pengasasan perangkat sendiri.

Dokumen terkait:

• Saluran: Menggunakan setChannel() dari Aplikasi Anda

unknown_version_build / semver_error

Penyebab

Versi dasar perangkat hilang (unknown) atau tidak valid semver.

Pemecahan masalah

• Set plugins.CapacitorUpdater.version ke versi semver yang valid 1.2.3.
• Sync dan membangun aplikasi native kembali.

Referensi dokumen terkait:

• Saluran: Versi Paket dan Saluran
• Pengaturan: Pembaruan tidak berlaku

unsupported_plugin_version

Penyebab

Versi plugin pembaruan terlalu tua untuk persyaratan backend saat ini.

Pengaturan

• Perbarui @capgo/capacitor-updater.
• Jalankan npx cap sync.
• Rebuild dan reinstall aplikasi native kembali.

disabled_platform_ios / disabled_platform_android

Penyebab

Saluran ini mematikan pembaruan untuk platform tersebut.

Pembetulan

• aktifkan toggle platform pada saluran.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Penyebab

Saluran ini melarang jenis konfigurasi atau target runtime saat ini.

Pembetulan

• sesuaikan opsi saluran (allow_prod, allow_dev, allow_device, allow_emulator) dengan target uji Anda.

key_id_mismatch

Penyebab

Kunci enkripsi bundle dan kunci perangkat berbeda.

Perbaiki

• Pakai kunci enkripsi yang sama/kunci publik di seluruh konfigurasi aplikasi dan alur kerja enkripsi bundle.

no_channel / null_channel_data

Penyebab

Tidak ada saluran yang valid yang ditentukan untuk perangkat.

Perbaiki

• Set default saluran di cloud, atau
• di bangun uji, atau defaultChannel atur ulang override saluran untuk perangkat.
• Dokumen terkait:

__CAPGO_KEEP_0__

• Saluran

on_premise_app

Penyebab

Backend mengembalikan HTTP 429 dengan on_premise_appHal ini terjadi dalam tiga situasi:

1. ID Aplikasi tidak ada di Capgo — perangkat mengirimkan app_id tidak terdaftar, sehingga backend tidak memiliki catatan tentangnya.
2. Aplikasi ditandai sebagai on-premise — aplikasi ada tetapi dikonfigurasi untuk pembaruan self-hosted, sehingga endpoint cloud Capgo menolak untuk menyajikannya.
3. Rencana organisasi dibatalkan — aplikasi organisasi tidak lagi memiliki langganan aktif.

Kesalahan umum

Ada kesalahan penulisan plugins.CapacitorUpdater.appId (di capacitor.config.ts) atau tidak sesuai dengan ID aplikasi yang terdaftar di dashboard Capgo. Backend tidak dapat membedakan “aplikasi tidak dikenal” dari “aplikasi on-premise”, sehingga kembali dengan kesalahan yang sama code.

Pemulihan

• Verifikasi app_id sama persis apa yang ditampilkan di dashboard Capgo (sensitif kasus).
• Jika aplikasi belum terdaftar, jalankan npx @capgo/cli@latest app add.
• Jika aplikasi sengaja on-premise, atur plugins.CapacitorUpdater.updateUrl ke endpoint update self-hosted Anda daripada URL cloud Capgo.
• Jika paket organisasi telah habis masa berlakunya, lanjutkan atau tingkatkan paket.

Daftar checklist diagnostik cepat

1. Pastikan ID aplikasi dan saluran yang benar untuk pembangunan.
2. Konfirmasi CapacitorUpdater.version Sesuai dengan versi aplikasi native yang terpasang.
3. Konfirmasi kebijakan saluran (disable_auto_update) sesuai dengan rencana peluncuran.
4. Konfirmasi pengaturan platform/target pembangunan memungkinkan perangkat ini.
5. Jalankan npx @capgo/cli@latest app debug dan baca kesalahan backend code.

Butuh bantuan lebih lanjut?

• Pengaturan
• Bagaimana mendapatkan dukungan

Teruskan dari Masalah Pembaruan Umum

Jika Anda menggunakan Masalah Pembaruan Umum untuk merencanakan pekerjaan plugin asli, hubungkannya dengan Menggunakan @capgo/capacitor-updater untuk kemampuan asli dalam Menggunakan @capgo/capacitor-updater, Direktori Plugin Capgo untuk alur kerja produk dalam Direktori Plugin Capgo, Plugin-Plugin Capacitor oleh Capgo untuk detail implementasi dalam Plugin-Plugin Capacitor oleh Capgo Mengambah atau Mengupdate Plugin __CAPGO_KEEP_0__ untuk detail implementasi di Mengambah atau Mengupdate Plugin, dan Alternatif Plugin Enterprise Ionic __CAPGO_KEEP_0__ untuk alur produk di Alternatif Plugin Enterprise Ionic.