トラブルシューティング

Solutions to common issues when building native apps with Capgo Cloud Build.

構築失敗

アップロード失敗または接続タイムアウト

症状:

• プロジェクトアップロード中にビルドが失敗する
• 60秒以内にタイムアウトエラー

解決策:

1. インターネット接続を確認する

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

2. プロジェクトサイズを削減する

   • 確保する node_modules/ アップロードされていない (自動除外されるはず)
   • プロジェクト内に大きなファイルがあるかどうか確認してください:

   find . -type f -size +10M

3. アップロード URL の有効期限を確認してください

   • アップロード URL は 1 時間で有効期限切れになります
   • 有効期限切れの URL エラーが発生した場合は、再度ビルドコマンドを実行してください

ヒント

非常に大きなプロジェクトではビルド時間制限に当たる可能性があります (参照) 既知の制限事項企業向けオプションについては、サポートに連絡してください

10分以内にビルドタイムアウト

症状：

• ビルド時間が最大許可時間を超えます
• ステータスは timeout

解決策：

1. 依存関係を最適化する

   • 未使用のnpmパッケージを削除する
   • ビルド npm prune --production ビルド前に

2. ネットワーク問題をビルド中に確認する

   • ビルド中に依存関係が大きなファイルをダウンロードする場合があります
   • キャッシュを事前に準備するにはロックファイルを使用します

3. ネイティブ依存関係を確認する

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

4. サポートに連絡する

   • あなたのアプリが正当にさらに時間が必要な場合
   • 特定のケースで制限を調整できます

認証問題

API キーが無効であるか、認証されていません

症状:

• 認証エラーでビルドが即座に失敗します。
• 401または403エラー

解決策:

1. APIキーが正しいことを確認してください

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

2. APIキーが正しいことを確認してください

   • キーには write または all 許可
   • Check in Capgo dashboard under API Keys

3. Ensure API key is being read

   # 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. 再認証

   bunx @capgo/cli@latest login

”App not found” or “No permission for this app”

Symptoms:

• Authentication works but app-specific error

Solutions:

1. Verify app is registered

   bunx @capgo/cli@latest app list

2. アプリIDが一致しているか確認

   • 確認 capacitor.config.json __CAPGO_KEEP_0__
   • 正しいアプリIDを使用しているコマンドがあるか確認

3. 組織へのアクセスを確認

   • 正しい組織にいるか確認
   • API キーはアプリの組織にアクセスできる必要があります

iOS ビルドの問題

Code サインインに失敗しました

症状:

• code署名フェーズでビルドが失敗する
• Xcodeは証明書またはプロファイルに関するエラーを表示する

解決策:

1. 証明書のタイプがビルドのタイプと一致することを確認する

   • 開発用ビルドには開発用証明書が必要
   • App Store用ビルドには配布用証明書が必要

2. 証明書とプロファイルが一致することを確認する

   # 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. プロビジョニングプロファイルが有効であることを確認する

   • 有効期限の確認
   • IDを含むことを確認してください
   • 証明書を含むことを確認してください

4. 資格情報を再生成してください

   • 古い証明書/プロファイルを削除してください
   • Apple Developer ポータルで新しいものを作成してください
   • 環境変数を再エンコードして更新してください

署名証明書が含まれていないプロビジョニング プロファイル

症状:

• Xcodeではプロファイルに証明書が見つかりません

解決策:

1. Appleから最新のプロファイルをダウンロードしてください

   • Apple Developer へ移動 → 証明書、ID、プロファイル
   • プロビジョニング プロファイルをダウンロード
   • プロファイルに証明書が含まれていることを確認

2. プロファイルに証明書が含まれていることを確認

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

3. 正しい証明書でプロファイルを再作成

   • Apple Developer ポータルでプロファイルを編集
   • 配布用証明書が選択されていることを確認
   • ダウンロードして再エンコード

App Store Connect の認証に失敗しました

症状:

• テストフライトへのアップロードが失敗する
• API キーに関するエラー

解決策:

1. API キー認証情報を確認する

   • APPLE_KEY_ID (10文字)を確認する
   • APPLE_ISSUER_ID (UUID形式)を確認する
   • APPLE_KEY_CONTENT が正しく base64 エンコードされていることを確認する

2. コンピュータの時刻を同期する

   • App Store Connect の認証では、ローカルシステムの時刻から短期間の JWT を生成します
   • Apple は、20 分以内に有効期限切れになるトークンを拒否します。時刻のずれが小さくても、有効なキーでもある場合でも、有効期限切れになる可能性があります。
   • Windows の場合、 設定 > 時間と言語 > 日付と時間 をクリック 現在の時間を同步
   • macOSの場合、 システム設定 > 一般 > 日付と時間 を有効にします
   • Linuxの場合、 timedatectl status を確認し、必要に応じてNTPを有効にします
   • Capgoのビルドまたは資格情報コマンドを再実行してください

   のドキュメントを参照してください Generating Tokens for API Requests の生成

3. APIをローカルでテストする

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

4. APIキーの権限を確認する

   • 「開発者」ロールまたはそれ以上が必要
   • App Store Connect -> ユーザーとアクセス -> キーで確認する

5. キーが取り消されていないことを確認する

   • App Store Connectで確認する
   • 必要なら新しいキーを作成する

「Pod install failed」

症状:

• CocoaPodsのインストール中にビルドが失敗します。
• Podfileエラー

解決策:

1. Podfile.lockがコミットされていることを確認する

   git status ios/App/Podfile.lock

2. ローカルでpod installをテストする

   cd ios/App
   pod install

3. 不互換のPodを確認する

   • Podfileのバージョン間の競合を確認する
   • iOSのデプロイメントターゲットに対応するすべてのPodを確認する

4. キャッシュをクリア

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

Android ビルドの問題

”Keystore password incorrect”

Symptoms:

• Build fails during signing
• Gradle errors about keystore

Solutions:

1. Verify keystore password

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

2. 環境変数を確認する

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

3. base64エンコードを確認する

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

”Key alias not found”

Symptoms:

• Signing fails with alias error

解決策:

1. キーストアのエイリアスの一覧を表示

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

2. エイリアスが完全に一致することを確認

   • エイリアスは大文字小文字区別
   • KEYSTORE_KEY_ALIASに誤字があるか確認

3. 正しいエイリアスをキーストアから使用

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

「Gradle ビルド失敗」

症状:

• 一般的なGradleエラー
• コンパイルまたは依存関係の問題

解決策:

1. ローカルでテストビルドを実行してください

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. 依存関係が欠けているかどうかを確認してください

   • build.gradleファイルを確認してください
   • すべてのプラグインが依存関係にリストされていることを確認してください

3. Gradleバージョンの互換性を確認してください

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

4. Gradle キャッシュをクリア

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

”Play Store upload failed”

Symptoms:

• Build succeeds but upload fails
• Service account errors

Solutions:

1. Verify service account JSON

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

2. サービスアカウントの権限を確認

   • Play Console → 設定 → API アクセスに移動
   • サービスアカウントがアプリにアクセスできることを確認
   • 「テストトラックへのリリース」権限を付与

3. Play Consoleでアプリが設定されていることを確認

   • Play Consoleでアプリを作成する必要があります
   • 少なくとも1つのAPKを手動でアップロードする必要があります

4. API が有効になっていることを確認

   • Google Play Developer API が有効になっていることを確認
   • Google Cloud Consoleで確認

一般的な問題

”Job not found” or “Build status unavailable”

症状:

• ビルドステータスの確認ができません
• ジョブIDのエラー

解決策:

1. しばらく待ってから再試行

   • ビルドジョブの初期化には数秒かかる場合があります

2. ジョブIDが正しいか確認してください

   • 初回ビルドのレスポンスからジョブIDを確認してください

3. ビルドが期限切れになっていないか確認してください

   • 24時間のビルドデータが利用可能です。

”Project sync failed”

Symptoms:

• Build fails before compilation starts
• Missing files errors

Solutions:

1. Run Capacitor sync locally

   bunx cap sync

2. Ensure all native files are committed

   git status ios/ android/

3. Gitで無視されているネイティブファイルを確認

   • 。gitignoreを確認
   • 重要な設定ファイルが無視されていないことを確認

”Build succeeded but I don’t see output”

Symptoms:

• Build shows success but no download link

Solutions:

1. Check build configuration

   • Artifact storage may not be configured
   • Contact support if artifact access is unavailable for your build

2. iOSのテストフライトの提出用

   • App Store Connectを確認する
   • アップロード後5-30分程度で処理が完了する

3. AndroidのPlay Store用

   • Play Console→テスト→内部テストを確認する
   • 処理時間は数分程度

CI/CD関連の問題

GitHubのアクション：「コマンドが見つかりません」

症状：

• bunx @capgo/cli@latest … CIで「コマンドが見つかりません」というエラーが発生する

ソリューション:

1. Bunを設定する なので bunx 利用可能:

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

2. 次に、CLIを実行 — bunx 必要なものは、オンデマンドで取得するだけです。グローバルインストールは必要ありません:

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

GitHubアクション: “シークレットが見つかりません”

症状:

• ビルド中の環境変数が空です

解決策:

1. シークレットが正しく設定されていることを確認する

   • リポジトリの設定 → シークレットと変数 → アクションに移動する
   • 必要なすべてのシークレットを追加する

2. 正しい構文を使用する

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

3. シークレット名が一致していることを確認する

   • 名前は大文字小文字区別される
   • シークレット参照に誤字がないことを確認する

さらにヘルプを取得する

詳細ログを有効にする

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

ビルド情報を収集

サポートに連絡する際には、次の情報を含めてください。

1. 使用したビルド コマンド

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

2. エラーメッセージ (フル アウトプット)

3. ジョブ ID (from build output)

4. ビルドログ (全てのターミナル出力をコピー)

5. 環境情報

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

サポートに連絡する

• メール: support@__CAPGO_KEEP_0__.app
• サポート: support@capgo.app
• ドキュメント: Capgo ドキュメント

既知の制限事項

現在の制限事項:

• 最大ビルド時間: 10 分
• 最大アップロードサイズ: ~500MB
• iOS ビルドには 24 時間の Mac のレンタルが必要です。Mac でビルドすると、最適な使用を確保するためにキューに追加されます。
• ビルドアーティファクトのダウンロードの可用性は、ビルド先とアーティファクトのストレージの構成に依存します。

これらの制限事項は、フィードバックに基づいて調整される可能性があります。

プリエスキャンが私のビルドをブロックしました

Capgoはローカルで プレースキャン アップロードする前にプレースキャンを実行します。報告された問題を修正するか、チェックID:

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

フルカタログを参照 プレースキャン チェック.

追加リソース

• はじめに 初期設定ガイド
• iOS ビルド - iOS用の設定
• Androidビルド - Android用の設定
• Prescanチェック - プリビルドの完全なチェックリストと無視フラグ
• CLI リファレンス - コマンドの完全なドキュメント