トラブルシューティング

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

ビルド失敗

”Upload failed” or “Connection timeout”

Symptoms:

• Build fails during project upload
• __CAPGO_KEEP_0__

解決策:

1. インターネット接続を確認してください

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

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

   • 確保 node_modules/ __CAPGO_KEEP_0__ (自動除外されるはず)
   • プロジェクト内の大きなファイルを確認してください:

   find . -type f -size +10M

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

   • URLをアップロードするには1時間以内に完了する必要があります。
   • URLが有効期限切れの場合、ビルドコマンドを再実行してください。

アドバイス

大規模プロジェクト（>200MB）ではタイムアウト制限に当たる可能性があります。エンタープライズオプションについてはサポートに問い合わせてください。

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
   npx @capgo/cli@latest app list

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

   • キーには write または all 権限
   • Capgo ダッシュボードの API キーを確認してください

3. API キーが正しく読み込まれていることを確認してください

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or verify local .capgo file
   cat .capgo

4. 再認証

   npx @capgo/cli@latest login

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

__CAPGO_KEEP_0__:

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

Solutions:

1. アプリの登録を確認する

   npx @capgo/cli@latest app list

2. アプリIDが一致するか確認する

   • 確認する capacitor.config.json appId
   • 正しいアプリ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 ポータルで新しいものを作成する
   • 環境変数を再エンコードして更新する

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

症状:

• 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 authentication failed”

Symptoms:

• Upload to TestFlight fails
• API key errors

Solutions:

1. Verify API key credentials

   • Check APPLE_KEY_ID (should be 10 characters)
   • Check APPLE_ISSUER_ID (should be UUID format)
   • APPLE_KEY_CONTENT が正しく base64 でエンコードされていることを確認する

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

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

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

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

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

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

”Pod install failed”

__CAPGO_KEEP_0__:

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

解決策:

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

   git status ios/App/Podfile.lock

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

   cd ios/App
   pod install

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

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

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

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

Android ビルド問題

”Keystore password incorrect”

Symptoms:

• 症状:
• 署名中にビルドが失敗する

Gradle から Keystore についてのエラーが発生する

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

”Key alias not found”

は見つかりませんでした

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

解決策:

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 build failed”

症状:

• 一般的な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:

• プレイストアアップロード失敗
• Service account errors

症状:

1. ビルドは成功しますがアップロードが失敗します。

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

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

   • Play Console へのアクセス設定に進みます → API
   • サービス アカウントがアプリにアクセスできるようにする
   • リリーステストトラックへの許可を付与

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

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

4. Capgoを使用している場合は、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”

症状:

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

解決策:

1. Capacitor をローカルで同步してください

   npx cap sync

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

   git status ios/ android/

3. gitignoreされているネイティブファイルを確認する

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

”Build succeeded but I don’t see output”

Symptoms:

• Build shows success but no download link

症状:

1. Check build configuration

   • Artifact storage may not be configured
   • アーティファクトのアクセスがビルドで利用できない場合、サポートに連絡してください。

2. iOSのTestFlightの提出用

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

3. AndroidのPlay Store用

   • Play Console → Testing → Internal testingを確認してください
   • アップロード後、処理に数分かかる場合があります

CI/CD固有の問題

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

症状:

• npx @capgo/cli CIで失敗

解決策：

1. Node.jsがインストールされていることを確認する

   - uses: actions/setup-node@v6
     with:
       node-version: '24'

2. CLIを明示的にインストールする

   - run: npm install -g @capgo/cli

GitHub Actions: “Secrets not found”

症状：

• ビルド時環境変数が空

解決策：

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

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

2. 正しい構文を使用

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

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

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

さらにヘルプを取得

詳細ログを有効にする

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

ビルド情報を収集

サポートに連絡する際には、以下を含めてください。

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

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

2. エラーメッセージ (フル出力)

3. ジョブID (ビルド出力から)

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

5. 環境情報

   node --version
   npm --version
   npx @capgo/cli --version

サポートに連絡

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

知見の制限

現在の制限:

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

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

追加リソース

• はじめに - 初期設定ガイド
• iOS ビルド - iOS用の設定
• Android ビルド - Android用の設定
• CLI リファレンス - 完全なコマンドドキュメント