Pemecahan Masalah

Solusi untuk masalah umum saat build native app dengan Capgo Cloud Build.

Build Gagal

“Upload failed” atau “Connection timeout”

Gejala:

• Build gagal saat upload proyek
• Error timeout setelah 60 detik

Solusi:

1. Periksa koneksi internet Anda

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. Perkecil ukuran proyek

   • Pastikan node_modules/ tidak ikut di-upload (seharusnya otomatis dikecualikan)
   • Periksa file berukuran besar di proyek Anda:

   find . -type f -size +10M

3. Cek masa berlaku URL upload

   • URL upload akan kedaluwarsa setelah 1 jam
   • Jika muncul error URL expired, jalankan ulang perintah build

Tips

Proyek yang sangat besar mungkin mencapai batas build-time (lihat Batasan yang Diketahui). Hubungi support untuk opsi enterprise.

“Build timeout setelah 10 menit”

Gejala:

• Build melebihi batas waktu maksimum
• Status menunjukkan timeout

Solusi:

1. Optimalkan dependencies

   • Hapus paket npm yang tidak terpakai
   • Gunakan npm prune --production sebelum melakukan build

2. Cek masalah jaringan saat build

   • Beberapa dependencies mungkin mengunduh file besar saat build
   • Pertimbangkan pre-caching dengan lock file

3. Tinjau dependensi native

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. Hubungi support

   • Jika aplikasi Anda memang butuh waktu lebih
   • Kami bisa menyesuaikan limit untuk kasus tertentu

Masalah Autentikasi

“API key tidak valid” atau “Unauthorized”

Gejala:

• Build gagal seketika dengan error autentikasi
• Error 401 atau 403

Solusi:

1. Verifikasi kunci API sudah benar

   # Test with a simple command
   bunx @capgo/cli@latest app list

2. Periksa izin key API

   • Kunci harus memiliki write atau all izin
   • Cek di dashboard Capgo di bagian API Keys

3. Pastikan kunci API terbaca

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. Autentikasi ulang

   bunx @capgo/cli@latest login

“App tidak ditemukan” atau “Tidak ada izin untuk app ini”

Gejala:

• Autentikasi berhasil tapi muncul error spesifik aplikasi

Solusi:

1. Verifikasi apakah aplikasi sudah terdaftar

   bunx @capgo/cli@latest app list

2. Cek kecocokan app ID

   • Verifikasi capacitor.config.json appId
   • Pastikan command menggunakan app ID yang benar

3. Verifikasi akses organisasi

   • Pastikan Anda berada di organisasi yang benar
   • Key API harus memiliki akses ke organisasi app

Masalah Build iOS

“Code signing gagal”

Gejala:

• Build gagal saat fase signing code
• Error Xcode terkait sertifikat atau profile

Solusi:

1. Pastikan tipe sertifikat sesuai tipe build

   • Development build butuh sertifikat Development
   • App Store build butuh sertifikat Distribution

2. Cek kecocokan sertifikat dan profile

   # Decode and inspect your certificate
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. Pastikan provisioning profile valid

   • Cek tanggal kedaluwarsa
   • Pastikan sudah termasuk App ID Anda
   • Pastikan sertifikat sudah termasuk

4. Regenerasi kredensial

   • Hapus sertifikat/profil lama
   • Buat yang baru di portal Apple Developer
   • Encode ulang dan perbarui environment variables

“Provisioning profile tidak menyertakan signing certificate”

Gejala:

• Xcode tidak dapat menemukan sertifikat di profil

Solusi:

1. Download profil terbaru dari Apple

   • Buka Apple Developer → Certificates, IDs & Profiles
   • Unduh provisioning profile
   • Pastikan profil ini menyertakan sertifikat Anda

2. Verifikasi sertifikat ada di profile

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. Buat ulang profile dengan sertifikat yang benar

   • Edit profile di portal Apple Developer
   • Pastikan distribution certificate Anda sudah terpilih
   • Unduh dan re-encode

“Autentikasi App Store Connect gagal”

Gejala:

• Gagal upload ke TestFlight
• Error pada key API

Solusi:

1. Verifikasi kredensial key API

   • Cek APPLE_KEY_ID (harus 10 karakter)
   • Cek APPLE_ISSUER_ID (harus format UUID)
   • Pastikan APPLE_KEY_CONTENT sudah di-encode base64 dengan benar

2. Sinkronkan jam komputer Anda

   • Autentikasi App Store Connect menggunakan JWT berdurasi singkat yang dibuat dari waktu sistem lokal Anda
   • Apple menolak token yang masa berlakunya lebih dari 20 menit ke depan, jadi sedikit saja perbedaan waktu dapat membuat key yang valid menjadi gagal
   • Di Windows, buka Pengaturan > Waktu & bahasa > Tanggal & waktu dan klik Sync sekarang
   • Di macOS, buka Pengaturan Sistem > Umum > Tanggal & Waktu dan aktifkan waktu otomatis
   • Di Linux, cek timedatectl status dan aktifkan NTP jika perlu
   • Setelah sinkronisasi, jalankan ulang perintah build atau credential Capgo

   Lihat dokumentasi Menghasilkan Token untuk Permintaan API Apple mengenai aturan masa berlaku token App Store Connect.

3. Tes kunci API secara lokal

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

4. Periksa izin key API

   • Key butuh role “Developer” atau lebih tinggi
   • Verifikasi di App Store Connect -> Users and Access -> Keys

5. Pastikan key tidak dicabut

   • Cek di App Store Connect
   • Generate key baru jika perlu

App crash saat launch di iOS 27

Gejala:

• App yang di-build dengan Xcode 27 langsung menutup sendiri di iOS 27 (TestFlight atau device)
• Laporan crash menunjukkan _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

Solusi: aplikasi yang dibangun dengan iOS 27 SDK harus menggunakan UIScene lifecycle. Tambahkan SceneDelegate dan UIApplicationSceneManifest ke ios/App/App/Info.plist, atau build menggunakan --xcode-version 26. Capgo sekarang memblokir build ini sebelum dimulai (pemeriksaan prescan ios/plist-scene-lifecycle-xcode27).

“Pod install gagal”

Peringatan

Capgo Build akan berhenti mendukung proyek CocoaPods pada Desember 2026. Migrasi ke Swift Package Manager: lihat Panduan Capacitor SPM.

Gejala:

• Build gagal saat instalasi CocoaPods
• Error pada Podfile

Solusi:

1. Pastikan Podfile.lock sudah di-commit

   git status ios/App/Podfile.lock

2. Coba pod install secara lokal

   cd ios/App
   pod install

3. Cek adanya pod yang tidak kompatibel

   • Periksa Podfile untuk konflik versi
   • Pastikan semua pod mendukung target deployment iOS Anda

4. Bersihkan cache pod

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

Masalah Build Android

“Password keystore salah”

Gejala:

• Build gagal saat proses signing
• Error Gradle terkait keystore

Solusi:

1. Verifikasi password keystore

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. Cek environment variables

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. Verifikasi base64 encoding

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

“Key alias tidak ditemukan”

Gejala:

• Signing gagal karena error alias

Solusi:

1. List alias keystore

   keytool -list -keystore my-release-key.keystore

2. Pastikan alias cocok persis

   • Alias bersifat case-sensitive
   • Cek typo pada KEYSTORE_KEY_ALIAS

3. Gunakan alias yang benar dari keystore

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

“Build Gradle gagal”

Gejala:

• Error Gradle umum
• Masalah kompilasi atau dependensi

Solusi:

1. Coba build secara lokal dulu

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. Cek dependensi yang hilang

   • Review file build.gradle
   • Pastikan semua plugin ada di dependencies

3. Periksa kompatibilitas versi Gradle

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. Hapus cache Gradle

   cd android
   ./gradlew clean
   rm -rf .gradle build

“Upload ke Play Store gagal”

Gejala:

• Build berhasil tapi upload gagal
• Error pada service account

Solusi:

1. Verifikasi JSON service account

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. Cek izin service account

   • Buka Play Console → Setup → Akses API
   • Pastikan service account punya akses ke aplikasi Anda
   • Berikan izin “Release to testing tracks”

3. Verifikasi aplikasi sudah diatur di Play Console

   • Aplikasi harus dibuat di Play Console terlebih dahulu
   • Minimal satu APK harus di-upload secara manual di awal

4. Cek apakah API sudah aktif

   • Google Play Developer API harus diaktifkan
   • Cek di Google Cloud Console

Masalah Umum

“Job tidak ditemukan” atau “Status build tidak tersedia”

Gejala:

• Tidak bisa cek status build
• Error pada Job ID

Solusi:

1. Tunggu sebentar dan coba lagi

   • Job build mungkin butuh beberapa detik untuk inisialisasi

2. Pastikan Job ID sudah benar

   • Verifikasi job ID dari respons build awal

3. Pastikan build belum kedaluwarsa

   • Data build tersedia selama 24 jam

“Sync project gagal”

Gejala:

• Build gagal sebelum kompilasi dimulai
• Error file tidak ditemukan

Solusi:

1. Jalankan Capacitor sync secara lokal

   bunx cap sync

2. Pastikan semua file native sudah di-commit

   git status ios/ android/

3. Cek file native yang masuk gitignore

   • Tinjau .gitignore
   • Pastikan file konfigurasi penting tidak di-ignore

“Build berhasil tapi output tidak muncul”

Gejala:

• Build sukses tapi link download tidak ada

Solusi:

1. Cek konfigurasi build

   • Penyimpanan artifact mungkin belum dikonfigurasi
   • Hubungi support jika akses artifact tidak tersedia untuk build Anda

2. Untuk submit ke TestFlight iOS

   • Cek App Store Connect
   • Proses mungkin memakan waktu 5-30 menit setelah upload

3. Untuk Android Play Store

   • Cek Play Console → Testing → Internal testing
   • Proses mungkin memakan waktu beberapa menit

Build berhasil tapi artifact salah setelah ganti environment

Gejala:

• Status build adalah success tapi IPA/AAB/APK tidak sesuai dengan branch atau flavor yang baru saja di-build
• Android AAB hilang atau salah setelah ganti kredensial RC vs production atau --android-flavor
• Build selesai terlalu cepat setelah mengubah signing config atau product flavor

Penyebab: Capgo memulihkan cache build per-app secara default (abaikan cache_key untuk shared general cache). Jika RC dan production menggunakan app ID yang sama tanpa key terpisah, proses restore bisa menggunakan kembali output kompilasi dari environment sebelumnya.

Solusi:

1. Gunakan cache key per environment (direkomendasikan untuk pipeline RC/PROD yang berjalan):

   # Production
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=prod \
     --android-flavor production
   
   # Staging / RC
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=staging \
     --android-flavor staging

2. Paksa satu clean build saat debugging:

   bunx @capgo/cli@latest build request com.example.app --platform android --no-cache

3. Di API atau integrasi webhook, berikan cache_key (contohnya "prod") atau atur cache_enabled: false untuk satu kali clean run.

Lihat Cache build untuk referensi opsi lengkapnya.

Masalah Spesifik CI/CD

GitHub Actions: “Command tidak ditemukan”

Gejala:

• bunx @capgo/cli@latest … gagal di CI dengan “command not found”

Solusi:

1. Siapkan Bun terlebih dahulu agar bunx is available:

   - uses: oven-sh/setup-bun@v2

2. Lalu jalankan CLI — bunx mengambilnya saat dibutuhkan, tanpa perlu install global:

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

GitHub Actions: “Secrets tidak ditemukan”

Gejala:

• Environment variables kosong saat build

Solusi:

1. Pastikan secrets sudah diatur

   • Buka repo Settings → Secrets and variables → Actions
   • Tambahkan semua secrets yang diperlukan

2. Gunakan sintaks yang benar

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. Pastikan nama secret sesuai

   • Nama bersifat case-sensitive
   • Tidak ada typo pada referensi secret

Butuh Bantuan Lebih Lanjut

Aktifkan Verbose Logging

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

Kumpulkan Informasi Build

Saat menghubungi support, sertakan:

1. Perintah build yang digunakan

   bunx @capgo/cli@latest build request com.example.app --platform ios

2. Pesan error (output lengkap)

3. ID Job (dari output build)

4. Log build (salin seluruh output terminal)

5. Info environment

   node --version
   npm --version
   bunx @capgo/cli@latest --version

Hubungi Support

• Discord: Gabung komunitas kami
• Email: support@capgo.app
• Dokumentasi: Dokumentasi Capgo

Batasan yang Diketahui

Batasan saat ini:

• Waktu build maksimal: 10 menit
• Ukuran upload maksimal: ~500MB
• Build iOS butuh sewa Mac 24 jam, build di Mac akan masuk antrean demi penggunaan optimal
• Ketersediaan download artifact build tergantung pada tujuan build dan konfigurasi penyimpanan artifact

Batasan ini dapat disesuaikan berdasarkan feedback.

Prescan memblokir build saya

Capgo menjalankan Capgo lokal prescan sebelum upload. Perbaiki temuan yang dilaporkan, atau abaikan hanya check id tersebut:

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

Lihat katalog lengkapnya: Pengecekan Prescan.

Sumber daya tambahan

• Panduan Memulai - Panduan setup awal
• Opsi Konfigurasi - flag CLI termasuk --cache-key dan --no-cache
• Build iOS - Konfigurasi khusus iOS
• Build Android - Konfigurasi khusus Android
• Pengecekan Prescan - Daftar lengkap pemeriksaan pre-build dan flag ignore
• Referensi CLI - Dokumentasi perintah lengkap