Masalah Pembaharuan Umum

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

Perlu dibaca terlebih dahulu

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

Kode Gagal Umum

disable_auto_update_to_major

Pemicu

Saluran Anda memblokir pembaruan besar (major upgrades)disable_auto_update = majordan versi utama bundle target lebih tinggi dari versi dasar perangkat.

Gejala umum

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 (misalnya 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 terpasang sekali:

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

Fix opsi B: lembagai kebijakan saluran

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

Referensi 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

Pemicu

Kebijakan saluran lebih ketat (atau) daripada pembaruan yang ditawarkan.minor Fix patchRelated docs:

Versi Target: Nonaktifkan Pembaruan Otomatis di Antara Versi Utama

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

Referensi dokumen terkait:

• Saluran: Matikan Strategi Auto Update

disable_auto_update_to_metadata

Penyebab

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

Pemecahan masalah

• Sinkronkan garis dasar perangkat (CapacitorUpdater.version) dengan versi aplikasi native yang terpasang, atau
• atur ulang min_update_version Strategi saluran.

Referensi dokumen terkait:

• Saluran: Nonaktifkan Strategi Perbarui Otomatis

disable_auto_update_under_native

Penyebab

Saluran mencegah penurunan di bawah garis dasar native.

Pemecahan masalah

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

Referensi dokumen terkait:

• Pengaturan Versi: Pencegahan Penurunan Otomatis

cannot_update_via_private_channel

Penyebab

Saluran yang dipilih/default tidak memungkinkan pengasosiasi perangkat secara otomatis.

Pemecahan Masalah

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

Dokumen terkait:

• Saluran: Menggunakan setChannel() dari Aplikasi Anda

unknown_version_build / semver_error

Penyebab

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

Perbaiki

• Atur plugins.CapacitorUpdater.version ke versi semver yang valid seperti Sync dan bangun kembali aplikasi native. 1.2.3.
• Dokumen terkait:

Saluran: Pengaturan Versi Paket dan Saluran

• Pengaturan: Perubahan tidak berlaku
• Judul bagian “versi_plugin_tidak_dipertahankan”

unsupported_plugin_version

Versi plugin pembaruan yang terlalu tua untuk persyaratan backend saat ini.

__CAPGO_KEEP_0__

Perbaiki

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

disabled_platform_ios / disabled_platform_android

Penyebab

Saluran memiliki pembaruan diaktifkan untuk platform tersebut.

Perbaiki

• Aktifkan toggle platform pada saluran.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Penyebab

Saluran melarang jenis build atau target runtime saat ini.

Perbaiki

• Sesuaikan opsi saluran (allow_prod, allow_dev, allow_device, allow_emulator) dengan target tes.

key_id_mismatch

Penyebab

Kunci enkripsi bundle dan kunci perangkat berbeda.

Perbaiki

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

• Atur default kanal cloud, atau
• set defaultChannel di bangun uji, atau
• tugaskan pengganti kanal untuk perangkat.

Dokumen terkait:

• Kanal

on_premise_app

Penyebab

Server backend mengembalikan HTTP 429 dengan on_premise_app. Hal ini terjadi dalam tiga situasi:

1. ID Aplikasi tidak ada di Capgo — yang app_id dikirim oleh perangkat 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 menyediakannya.
3. Rencana organisasi dibatalkan — aplikasi organisasi tidak lagi memiliki langganan aktif.

Kesalahan umum

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

Perbaiki

• Periksa apakah app_id sama persis dengan yang ditampilkan di Capgo dashboard (case-sensitive).
• 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 kepada endpoint pembaruan self-hosted Anda daripada URL cloud Capgo.
• If the organization plan expired, renew or upgrade the plan.

Daftar Periksa Cepat

1. Pastikan ID aplikasi dan saluran benar untuk build ini.
2. Pastikan CapacitorUpdater.version sama dengan versi aplikasi native yang terpasang.
3. Pastikan kebijakan saluran (disable_auto_update) sesuai dengan rencana peluncuran yang diinginkan.
4. Pastikan toggle platform/build memungkinkan perangkat ini.
5. Jalankan dan baca kesalahan backend __CAPGO_KEEP_0__. npx @capgo/cli@latest app debug and read backend error code.

Bab yang berjudul “Memerlukan bantuan lebih lanjut?”

• Cara mendapatkan dukungan
• Lanjutkan dari Masalah Pembaruan Umum

Bab yang berjudul “Lanjutkan dari Masalah Pembaruan Umum”

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