トラブルシューティング

Capgo Cloud Build でネイティブアプリをビルドする際によくある問題の解決策。

Buildの失敗

「Upload failed」または「Connection timeout」

症状:

• プロジェクトのアップロード中にビルドが失敗する
• 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 key invalid” または “Unauthorized”

症状:

• 認証エラーでビルドがすぐに失敗する
• 401 または 403 エラー

解決策:

1. API キーが正しいか確認

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

2. API キーの権限を確認

   • キーには write または all 権限が必要です
   • Capgo ダッシュボードの API Keys で確認

3. API キーが読み取られていることを確認

   # 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” または “No permission for this app”

症状:

• 認証は成功しているが、アプリ固有のエラーが発生

解決策:

1. アプリが登録されていることを確認

   bunx @capgo/cli@latest app list

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

   • 確認 capacitor.config.json appId
   • コマンドで正しいアプリIDを使用していることを確認

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

   • 正しい組織にいることを確認
   • API キーには、アプリの組織へのアクセス権が必要です

iOS ビルドの問題

“Code の署名に失敗しました”

症状:

• code の署名フェーズでビルドが失敗する
• 証明書やプロファイルに関する Xcode のエラー

解決策:

1. 証明書の種類がビルドタイプと一致しているか確認

   • Development ビルドには Development 証明書が必要です
   • App Store ビルドには Distribution 証明書が必要です

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. Provisioning profile が有効であることを確認

   • 有効期限を確認
   • App ID が含まれているか確認
   • 証明書が含まれていることを確認

4. 認証情報を再生成

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

「プロビジョニングプロファイルに署名用証明書が含まれていません」

症状:

• Xcode がプロファイル内の証明書を見つけられない

解決策:

1. Apple から最新のプロファイルをダウンロード

   • Apple Developer → Certificates, IDs & Profiles に移動
   • プロビジョニングプロファイルをダウンロード
   • 証明書が含まれていることを確認してください

2. プロファイル内に証明書があるか確認

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

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

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

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

症状:

• TestFlightへのアップロードが失敗する
• 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 のビルドまたは認証情報コマンドを再実行します

   Apple の API リクエスト用のトークン生成 ドキュメントで、App Store Connect のトークン有効期限ルールを確認してください。

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

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

4. API キーの権限を確認

   • キーには「Developer」ロール以上の権限が必要です
   • App Store Connect -> ユーザーとアクセス -> キーで確認してください

5. キーが失効していないことを確認してください

   • App Store Connectで確認してください
   • 必要に応じて新しいキーを生成してください

iOS 27でアプリが起動時にクラッシュする

症状:

• Xcode 27でビルドしたアプリがiOS 27（TestFlightまたは実機）で即座に閉じてしまいます
• クラッシュレポートには以下が表示されます _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

解決策: iOS 27 の SDK でビルドしたアプリは、UIScene ライフサイクルの採用が必須です。追加してください SceneDelegate と UIApplicationSceneManifest まで ios/App/App/Info.plistを追加するか、 --xcode-version 26でビルドしてください。Capgo は、これらのビルド開始前にブロックします（プリスキャンチェック ios/plist-scene-lifecycle-xcode27).

「Pod install failed」が発生した場合

注意

Capgo Build は 2026 年 12 月に CocoaPods プロジェクトのビルドを停止します。Swift Package Manager への移行方法はこちら： Capacitor SPM ガイド.

症状:

• CocoaPods インストール中にビルドが失敗する
• Podfile エラー

解決策:

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

   git status ios/App/Podfile.lock

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

   cd ios/App
   pod install

3. 非互換の pod を確認

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

4. Podキャッシュをクリアする

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

Android ビルドの問題

「Keystore password incorrect」

症状:

• 署名中にビルドが失敗する
• keystoreに関するGradleエラー

解決策:

1. Keystoreパスワードの確認

   # 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」

症状:

• エイリアスエラーで署名が失敗する

解決策:

1. keystoreのエイリアス一覧を表示

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

2. エイリアスが完全に一致しているか確認

   • エイリアスは大文字・小文字を区別します
   • KEYSTORE_KEY_ALIASのタイポを確認

3. keystoreから正しいエイリアスを使用

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

「Gradle build failed」が発生しました

症状:

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

解決策:

1. まずローカルでビルドを試す

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. 依存関係の不足を確認する

   • build.gradleファイルを確認する
   • すべてのプラグインが dependencies に含まれているか確認する

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」

症状:

• ビルドは成功するがアップロードが失敗
• サービスアカウントのエラー

解決策:

1. サービスアカウントの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」または「Build status unavailable」

症状:

• ビルドステータスを確認できない
• Job IDのエラー

解決策:

1. 少し待ってから再試行する

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

2. Job IDが正しいか確認する

   • 初期ビルドレスポンスからジョブIDを確認する

3. ビルドの有効期限が切れていないか確認する

   • ビルドデータは24時間利用可能

「Project sync failed」

症状:

• コンパイル開始前にビルドが失敗する
• ファイルが見つからないエラー

解決策:

1. ローカルで Capacitor sync を実行する

   bunx cap sync

2. すべてのネイティブファイルがコミットされていることを確認

   git status ios/ android/

3. gitignore されているネイティブファイルがないか確認

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

「Build succeeded but I don’t see output」

症状:

• ビルドは成功したがダウンロードリンクが表示されない

解決策:

1. ビルド設定を確認

   • アーティファクトストレージが未設定の可能性があります
   • ビルドのアーティファクトにアクセスできない場合は、サポートにお問い合わせください

2. iOS TestFlightへの提出について

   • App Store Connectを確認してください
   • アップロード後、処理に5〜30分かかる場合があります

3. Android Play Storeの場合

   • Play Console → テスト → 内部テストを確認してください
   • 処理に数分かかる場合があります

ビルドは成功したが、環境切り替え後にアーティファクトが正しくない

症状:

• ビルドステータスは success しかし、IPA/AAB/APKが、今ビルドしたブランチやflavorと一致しない
• RCとproductionの認証情報を切り替えた後、Android AABが見つからない、または内容が正しくない --android-flavor
• 署名設定やproduct flavorを変更した直後、ビルドが異常に早く終了する

原因: Capgo は アプリごとのビルドキャッシュを デフォルトで復元します（共有の cache_key general cacheを使用する場合は省略）。RCとproductionで、個別のキーを使わずに同じapp IDを共有している場合、復元時に前の環境のコンパイル済み出力が再利用されることがあります。

解決策:

1. 環境ごとにキャッシュキーを使用してください （継続的なRC/PRODパイプラインでは推奨）:

   # 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. クリーンビルドを強制する デバッグ時:

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

3. API または Webhook 統合で、を渡す cache_key (例: "prod") または設定する cache_enabled: false 1 回のクリーン実行のために。

詳細は ビルドキャッシュ 全オプションのリファレンスはこちら。

CI/CD 固有の問題

GitHub Actions: 「Command not found」

症状:

• bunx @capgo/cli@latest … CIで「command not found」エラーになる

解決策:

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 Actions: 「Secrets not found」

症状:

• ビルド時に環境変数が空になる場合

解決策:

1. Secrets が設定されているか確認

   • リポジトリの Settings → Secrets and variables → Actions に移動
   • 必要なすべての Secrets を追加

2. 正しい構文を使用

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

3. シークレット名が一致しているか確認

   • 名前は大文字小文字を区別します
   • シークレット参照に誤字がないか

サポートを受ける

Verbose Loggingを有効にする

# 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 (ビルド出力より)

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

5. 環境情報

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

サポートに問い合わせる

• Discord: コミュニティに参加する
• メールアドレス: support@capgo.app
• ドキュメント: Capgo ドキュメント

既知の制限事項

現在の制限事項:

• ビルド時間の上限: 10分
• アップロードサイズの上限: 約500MB
• iOSビルドには24時間のMacリースが必要です。最適な利用のため、Macでのビルドはキューに入ります
• ビルド成果物のダウンロード可否は、ビルド先と成果物ストレージの設定に依存します

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

Prescan にビルドをブロックされた

Capgo はローカルで実行します プリスキャン アップロード前に。報告された指摘を修正するか、そのチェックIDだけを無視してください:

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

カタログ全一覧はこちら： プリスキャンチェック.

関連リソース

• スタートガイド - 初期セットアップガイド
• 設定オプション - CLI フラグ（以下を含む） --cache-key と --no-cache
• iOS ビルド - iOS専用の設定
• Android ビルド - Android固有の設定
• プリスキャンチェック - プリビルドチェックと無視フラグの完全なリスト
• CLI リファレンス - 完全なコマンドドキュメント