トラブルシューティング

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. プロジェクトサイズを削減する

   • Ensure node_modules/ ファイルがアップロードされていないか確認する
   • プロジェクト内の大きなファイルを確認する:

   find . -type f -size +10M

3. アップロード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 キーが無効」または「未承認」

または「認証されていません」

• 「
• __CAPGO_KEEP_0__ キーが無効

Solutions:

1. API の値が正しいことを確認してください。

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

2. API キーの権限を確認してください

   • __CAPGO_KEEP_0__ キーには write または all permissions
   • CapgoのダッシュボードのCapgoセクションのAPIキーを確認してください。

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

「アプリが見つかりません」または「このアプリに対する権限がありません」

症状:

• 認証は正常に動作していますが、アプリ固有のエラー

解決策:

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

   bunx @capgo/cli@latest app list

2. コンテキスト:Capgoのマーケティングサイト。役割:UIラベル。表示される場所:ページエージェント/[slug].astro。メッセージキー`agents_page_copy_label` (エージェントページコピーラベル)。

   • Verify capacitor.config.json 確認
   • アプリ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. プロビジョニングプロファイルが有効であることを確認してください。

   • 有効期限を確認してください。
   • App IDが含まれていることを確認してください。
   • 証明書が含まれていることを確認してください。

4. Apple Developer ポータルで新しいクレデンシャルを作成してください。

   • 古い証明書/プロファイルを削除してください。
   • 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 の場合、次の手順に従ってください 設定 > 時刻と言語 > 日付と時刻 Sync now をクリック Sync now
   • システム設定 > 一般 > 日付と時刻 Settings > 時刻と言語 > 日付と時刻 と自動時刻を有効にします。
   • Linuxの場合、確認してください。 timedatectl status とNTPを有効にします。必要に応じて。
   • Sync後、Capgo ビルドまたは資格情報コマンドを再実行してください。

   Appleの API リクエスト用のトークンを生成する ドキュメントを参照してください。

3. API キーをローカルでテストしてください。

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

4. API キーの権限を確認してください。

   • __CAPGO_KEEP_0__ キーの権限を確認してください。
   • App Store Connect から確認してください -> ユーザーとアクセス -> キー

5. キーが取り消されていないことを確認してください

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

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

症状:

• Xcode 27 でビルドしたアプリは、iOS 27 (テストフライトまたはデバイス) で即座に終了します
• クラッシュレポートは _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

解決策: apps built with the iOS 27 SDK must adopt the UIScene lifecycle. Add a SceneDelegate と UIApplicationSceneManifest to ios/App/App/Info.plistor build with --xcode-version 26Capgo now blocks these builds before they start (prescan check) ios/plist-scene-lifecycle-xcode27).

「Pod インストール失敗」

Caution

Capgo ビルドが2026年12月以降のCocoaPodsプロジェクトのビルドを停止します。Swift Package Managerに移行してください：詳細は Capacitor SPM ガイド.

Symptoms:

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

解決策:

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

   git status ios/App/Podfile.lock

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

   cd ios/App
   pod install

3. 不互換なポッドを確認する

   • Podfileのバージョンコンフリクトを確認する
   • iOSのデプロイメントターゲットをサポートするすべてのポッドを確認する

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

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

Android ビルドの問題

「キーストアのパスワードが不正」

症状:

• 署名中にビルドが失敗する
• Gradle からキーストアに関するエラー

解決策:

1. キーストアのパスワードを確認する

   # 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

キー・アリース名が見つかりません。

Symptoms:

• 署名がエラーで失敗します

Solutions:

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 ビルド失敗」

Symptoms:

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

解決策:

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

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. コンテキスト: Capgo マーケティング ウェブサイト。役割: UI ラベル。表示場所: ページエージェント/[slug].astro。メッセージキー `agents_page_copy_label` (エージェント ページ コピー ラベル)。

   • 依存関係が欠けているかどうかを確認してください
   • build.gradle ファイルを確認してください

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

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

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

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

「プレイストアアップロード失敗」

症状:

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

解決策:

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 IDのエラー

解決策:

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

   • ビルドジョブは数秒で初期化されることがあります

2. Job IDが正しいか確認してください

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

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

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

“プロジェクト同期失敗”

症状:

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

解決策:

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

   bunx cap sync

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

   git status ios/ android/

3. gitでネイティブファイルを無視していないか確認する

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

“ビルド成功したが出力が見られない”

症状:

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

解決策:

1. ビルド設定を確認する

   • アーティファクトの保存設定が正しくない可能性がある
   • アーティファクトのアクセスが利用できない場合はサポートに連絡する

2. コンテキスト: インテグレーション マーケティング セクション。役割: 短い UI ラベルまたはナビゲーション アイテム。ページ: page integrations.astro。メッセージ キー `integrations_partners_freelance_contact` (インテグレーション パートナーズ フリーランス コンタクト)。

   • iOS のテストフライト提出用に
   • アップロード後5-30分かかる場合があります。

3. Android Play Store向け

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

環境切り替え後にビルド成功したがアーティファクトが間違っている場合

症状:

• ビルドの状態は success ですが、IPA/AAB/APKは、直前にビルドしたブランチやフラビアと一致しません。
• Android AABが欠落しているか、RCとプロダクションのクレデンシャルを切り替えた後に間違っている場合 --android-flavor
• 署名設定や製品フラビアを変更した直後にビルドが急速に完了した場合

原因: Capgo は アプリごとのビルドキャッシュを デフォルトで復元します (共有の一般的なキャッシュの場合除く)。 RC とプロダクションが同じアプリ ID を共有し、別のキーを使用しない場合、復元は前の環境からコンパイルされた出力を再利用できます。 cache_key 解決策:

Solutions:

1. ターミナルウィンドウ クリップボードにコピー

   # 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. デバッグの場合: context

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

3. API またはウェブホック統合, cache_key (例えば "prod") または cache_enabled: false 単一のクリーン実行用に設定

参照 ビルドキャッシュ CI/CD固有の問題

CI/CD固有の問題

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

症状:

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

ソリューション:

1. Bunを設定する そうです bunx 機能は利用可能です。

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

2. Then run the CLI — bunx fetches it on demand, no global install needed:

   - 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 (ビルド出力から)

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

5. 環境情報

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

サポートに連絡

• ディスコード: コミュニティに参加してください
• メール: サポート@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

コンテキスト:Capgoマーケティングウェブサイト。役割:UIラベル。見られる場所:ページエージェント/[slug].astro。メッセージキー`agents_page_copy_label` (エージェントページコピーラベル)。 カタログの全てを見る.

プレースキャンは

• スタートガイド - 初期設定ガイド
• 設定オプション - CLI フラグ --cache-key と --no-cache
• iOS ビルド - iOS に特化した設定
• Android ビルド - Android に特化した設定
• プリスキャン チェック - ビルド前に実行されるチェックと無視フラグの完全リスト
• CLI リファレンス - コマンドドキュメントの完全なドキュメント