Masalah Update Umum

Saat pengecekan update gagal, Capgo biasanya mengembalikan error code dan message di dalam /updates respons. Halaman ini menjelaskan kegagalan yang paling umum dan perbaikan tercepat.

Baca ini dulu

• no_new_version_available adalah kondisi normal, bukan kegagalan.
• Banyak laporan “update ditemukan tetapi tidak diterapkan” disebabkan oleh penolakan kebijakan/konfigurasi, bukan keterlambatan cache, terutama jika respons menyertakan error code.
• Gunakan npx @capgo/cli@latest app debug saat mereproduksi masalah untuk melihat detail request/response.

Kode kegagalan umum

provider_infrastructure_request_blocked

Penyebab

Aplikasi memiliki Blokir request infrastruktur provider diaktifkan dan request berasal dari rentang IP datacenter Google atau Apple yang dikenal. Capgo memblokir request ini pada /updates, /stats, dan /channel_self untuk mencegah lalu lintas dari provider dianggap sebagai lalu lintas perangkat.

Perbaikan

• Reproduksi update dari perangkat fisik di jaringan pengguna biasa.
• Jangan gunakan probe cloud-hosted atau runner datacenter provider untuk pengecekan updater, stats, atau channel-self saat perlindungan ini aktif.
• Jika lalu lintas tersebut disengaja, buka tab Informasi aplikasi Anda dan matikan Blokir permintaan infrastruktur provider. Aktifkan kembali setelah pengujian selesai.

Aplikasi baru memiliki perlindungan ini aktif secara default. Aplikasi yang dibuat sebelum pengaturan ini diperkenalkan tetap nonaktif hingga Anda mengaktifkannya.

Detail respons

• /updates menjaga kontrak respons updater dan mengembalikan HTTP 200. Body-nya berisi error, message, kind: "blocked", dan provider ("google" atau "apple").
• /stats dan /channel_self mengembalikan HTTP 429 dengan error code yang sama. Anggap ini sebagai blokir kebijakan yang disengaja, bukan kondisi retry sementara.

disable_auto_update_to_major

Penyebab

Channel Anda memblokir upgrade mayor (disable_auto_update = major) dan versi mayor target bundle lebih tinggi dari versi baseline perangkat.

Gejala umum

version: 1.0.8 dengan old: 0.0.0 artinya perangkat melaporkan baseline 0.0.0, sehingga upgrade major ditolak.

Cara menginterpretasikannya

Backend membandingkan versi major menggunakan baseline perangkat old dan target version.

• Jika target adalah 1.0.1, baseline major harus 1 (contohnya 1.0.0).
• Jika target adalah 10.0.1, baseline major harus 10 (contohnya 10.0.0).

Opsi perbaikan A (disarankan): samakan major baseline perangkat

Atur plugins.CapacitorUpdater.version di capacitor.config.* sehingga MAJOR cocok dengan MAJOR bundle 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 terinstal satu kali:

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

Solusi opsi B: longgarkan kebijakan channel

Izinkan cross-major auto-updates di pengaturan channel (hanya jika strategi rollout tersebut memang disengaja).

Dokumentasi terkait:

• Version Targeting: Nonaktifkan Auto-Update Antar Versi Mayor
• Channels: Nonaktifkan strategi Auto Update

disable_auto_update_to_minor / disable_auto_update_to_patch

Penyebab

Kebijakan channel lebih ketat (minor atau patch) daripada update yang ditawarkan.

• minor memblokir jika target bundle memiliki nomor mayor atau minor yang berbeda dari baseline native perangkat (version_build). Contoh: 1.2.3 -> 1.3.0 diblokir.
• patch memblokir perubahan nomor major, minor, atau patch dari version_build. Hanya perubahan suffix 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.

Perbaikan

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

Dokumentasi terkait:

• Channels: Nonaktifkan strategi Auto Update

disable_auto_update_to_metadata

Penyebab

Channel menggunakan targeting berbasis metadata (version_number) dan baseline perangkat di bawah yang disyaratkan min_update_version.

Perbaikan

• Selaraskan baseline perangkat (CapacitorUpdater.version) dengan versi native app yang terpasang, atau
• sesuaikan min_update_version / strategi channel.

Dokumentasi terkait:

• Channels: Nonaktifkan strategi Auto Update

disable_auto_update_under_native

Penyebab

Channel mencegah downgrade di bawah baseline native.

Perbaikan

• Upload versi bundle yang lebih besar atau sama dengan baseline native, atau
• nonaktifkan proteksi downgrade “under native” untuk channel tersebut.

Dokumentasi terkait:

• Targeting Versi: Pencegahan Auto-Downgrade

cannot_update_via_private_channel

Penyebab

Channel yang dipilih/default tidak mengizinkan self-assignment perangkat.

Perbaikan

• Gunakan channel lain dengan self-assignment aktif, atau
• jadikan channel publik / aktifkan self-assignment.

Dokumentasi terkait:

• Channels: Menggunakan setChannel() dari Aplikasi Anda

unknown_version_build / semver_error

Penyebab

Versi baseline perangkat tidak ditemukan (unknown) atau bukan semver yang valid.

Perbaikan

• Atur plugins.CapacitorUpdater.version dengan semver yang valid seperti 1.2.3.
• Sinkronkan dan rebuild native app.

Dokumentasi terkait:

• Channels: Bundle Versioning dan Channels
• Troubleshooting: Update tidak diterapkan

unsupported_plugin_version

Penyebab

Versi plugin Updater terlalu lama untuk persyaratan backend saat ini.

Perbaikan

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

disabled_platform_ios / disabled_platform_android

Penyebab

Update di channel dinonaktifkan untuk platform tersebut.

Perbaikan

• Aktifkan toggle platform pada channel.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Penyebab

Channel melarang tipe build atau target runtime saat ini.

Perbaikan

• Sesuaikan opsi channel (allow_prod, allow_dev, allow_device, allow_emulator) dengan target pengujian Anda.

key_id_mismatch

Penyebab

Bundle encryption key dan device key berbeda.

Perbaikan

• Gunakan encryption key/public key yang sama pada konfigurasi app dan workflow enkripsi bundle.

no_channel / null_channel_data

Penyebab

Tidak ada channel valid yang ditemukan untuk perangkat ini.

Perbaikan

• Atur channel default cloud, atau
• atur defaultChannel di test build, atau
• tetapkan channel override untuk perangkat.

Dokumentasi terkait:

• Channel

on_premise_app

Penyebab

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

1. App ID tidak ada di Capgo — app_id yang dikirim perangkat tidak terdaftar, sehingga backend tidak memiliki rekamannya.
2. App ditandai sebagai on-premise — app ada tetapi dikonfigurasi untuk update self-hosted, sehingga endpoint cloud Capgo menolak melayaninya.
3. Plan organisasi dibatalkan — organisasi app tidak lagi memiliki langganan aktif.

Kesalahan umum

Salah ketik pada plugins.CapacitorUpdater.appId (di capacitor.config.ts) atau tidak cocok dengan app ID yang terdaftar di dashboard Capgo. Backend tidak bisa membedakan “unknown app” dari “on-premise app”, sehingga mengembalikan error code yang sama.

Perbaikan

• Pastikan app_id sama persis dengan yang ditampilkan di dashboard Capgo (case-sensitive).
• Jika app belum terdaftar, jalankan npx @capgo/cli@latest app add.
• Jika app memang sengaja di-on-premise, atur plugins.CapacitorUpdater.updateUrl ke endpoint update self-hosted Anda, bukan ke URL cloud Capgo.
• Jika paket organisasi sudah kedaluwarsa, perpanjang atau upgrade paketnya.

Checklist diagnostik cepat

1. Pastikan app ID dan channel sudah benar untuk build ini.
2. Konfirmasi CapacitorUpdater.version cocok dengan versi aplikasi native yang terpasang.
3. Konfirmasi kebijakan channel (disable_auto_update) sesuai dengan rencana rollout.
4. Pastikan toggle platform/build target mengizinkan perangkat ini.
5. Jalankan npx @capgo/cli@latest app debug dan baca error backend code.

Butuh bantuan lebih lanjut?

• Pemecahan Masalah
• Cara mendapatkan bantuan

Lanjutkan dari Masalah Update Umum

Jika Anda menggunakan Masalah Update Umum untuk merencanakan pekerjaan plugin native, hubungkan dengan Menggunakan @capgo/capacitor-updater untuk fitur native di bagian Menggunakan @capgo/capacitor-updater, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi di Menambahkan atau Memperbarui Plugin, dan Alternatif Plugin Ionic Enterprise untuk alur kerja produk dalam Alternatif Plugin Ionic Enterprise.