よくあるアップデートの問題

アップデートの確認に失敗した場合、通常 Capgo は error code と message を /updates レスポンスに返します。このページでは、よくあるエラーとその迅速な解決策について説明します。

まずはこちらをお読みください

• no_new_version_available エラーではなく正常な状態です。
• 「アップデートが見つかりましたが適用されませんでした」という報告の多くは、キャッシュの遅延ではなく、ポリシーや設定による拒否です。特にレスポンスに明示的な error code
• 使用するのは npx @capgo/cli@latest app debug リクエスト/レスポンスの詳細を確認するために、問題を再現している間。

よくあるエラーコード

provider_infrastructure_request_blocked

原因

アプリで プロバイダーのインフラへのリクエストがブロックされている が有効になっており、リクエストが既知のGoogleまたはAppleのデータセンターIP範囲から送信されました。Capgo は、これらのリクエストを /updates, /stats、および /channel_self プロバイダー由来のトラフィックがデバイスのトラフィックとして扱われるのを防ぐためにブロックします。

修正

• 通常のユーザーネットワーク環境下の実機を使用して、アップデートの再現を行ってください。
• この保護機能が有効な間は、updater、stats、またはchannel-selfのチェックに、クラウドホストのプローブやプロバイダーのデータセンターランナーを使用しないでください。
• もしそのトラフィックが意図的なものである場合は、アプリの 情報 タブを開き、 プロバイダーのインフラへのリクエストがブロックされているをオフにしてください。テスト完了後に再度有効にしてください。

新しいアプリでは、この保護機能がデフォルトで有効になっています。この設定が導入される前に作成されたアプリは、手動で有効にするまで無効のままです。

レスポンスの詳細

• /updates updaterのレスポンス規約を維持し、HTTP 200を返します。そのボディには以下が含まれます error, message, kind: "blocked"、および provider ("google" または "apple").
• /stats と /channel_self HTTPエラーを返します 429 同じエラー code が発生します。これは一時的なリトライ対象ではなく、意図的なポリシーによるブロックとして扱ってください。

disable_auto_update_to_major

原因

設定されているチャンネルがメジャーアップデートを制限しており（disable_auto_update = major）、ターゲットとなるbundleのメジャーバージョンがデバイスのベースラインバージョンを上回っています。

典型的な症状

version: 1.0.8 と old: 0.0.0 デバイスがベースラインを報告していることを意味します 0.0.0、そのためメジャーアップグレードは拒否されます。

解釈の仕方

バックエンドはデバイスのbaselineと old およびターゲット version.

• targetが 1.0.1の場合、baselineのメジャーバージョンは 1 である必要があります（例： 1.0.0).
• targetが 10.0.1の場合、baselineのメジャーバージョンは 10 である必要があります（例： 10.0.0).

修正オプション A（推奨）: デバイスbaselineのメジャーバージョンを揃える

設定 plugins.CapacitorUpdater.version 内の capacitor.config.* つまり、 メジャー バージョンが、配信したいバンドルのメジャーバージョンと一致している必要があります（例： 1.0.0 の 1.0.1, 10.0.0 の 10.0.1).

その後、インストール済みのアプリにこの設定を一度適用してください：

1. 実行する npx cap sync.
2. ネイティブアプリを再ビルドして再インストールします。

解決策 B: チャネルポリシーを緩和する

チャネル設定でメジャーバージョンを跨いだ自動アップデートを許可します（そのロールアウト戦略が意図的な場合のみ）。

関連ドキュメント：

• バージョンのターゲット指定: メジャーバージョン間での自動更新を無効化する
• Channels: 自動更新戦略の無効化

disable_auto_update_to_minor / disable_auto_update_to_patch

原因

Channelのポリシーが、提供されているアップデートよりも厳格な場合（minor または patch）に発生します。

• minor ターゲットとなるbundleのメジャーまたはマイナーバージョンが、デバイスのNative Buildのベースラインと異なる場合にブロックされます（version_build）。例： 1.2.3 -> 1.3.0 はブロックされます。
• patch は、以下のバージョンからのメジャー、マイナー、またはパッチ番号の変更をすべてブロックします： version_build。サフィックスの変更のみが許可されます。 MAJOR.MINOR.PATCH 次のように同一のままです： 1.0.0-beta.1 -> 1.0.0-beta.2 または 1.0.0+build.1 -> 1.0.0+build.2.

修正

• 現在のポリシーに適合するbundleをuploadするか、
• dashboard/CLIでchannelのポリシーを変更してください。

関連ドキュメント：

• Channels: Auto Update戦略の無効化

disable_auto_update_to_metadata

原因

Channelがmetadataベースのターゲティング（version_number) を使用しており、デバイスのbaselineが要件を満たしていない min_update_version.

修正

• デバイスのベースライン（CapacitorUpdater.version）をインストール済みのネイティブアプリのバージョンに合わせるか、
• 調整 min_update_version / チャンネル戦略。

関連ドキュメント:

• チャンネル: Auto Update 戦略の無効化

disable_auto_update_under_native

原因

チャンネルがネイティブのベースライン未満へのダウングレードを防いでいます。

修正

• ネイティブのベースライン以上の bundle バージョンを upload するか、
• そのチャンネルの「under native」ダウングレード保護を無効にしてください。

関連ドキュメント:

• バージョンターゲティング：自動ダウングレード防止

cannot_update_via_private_channel

原因

選択中またはデフォルトのチャンネルでは、デバイスのセルフアサインが許可されていません。

修正

• セルフアサインが有効な別のチャンネルを使用するか、
• チャンネルを公開するか、セルフアサインを有効にしてください。

関連ドキュメント:

• Channels: アプリから setChannel() を使用する

unknown_version_build / semver_error

原因

デバイスのベースラインバージョンが見つかりません（unknown）または 有効なsemverではありません.

修正

• 設定 plugins.CapacitorUpdater.version への 有効なsemverではありません のような 1.2.3.
• ネイティブアプリをSyncして再ビルドしてください。

関連ドキュメント:

• Channels: バンドルバージョニングとChannelsについて
• トラブルシューティング: アップデートが適用されない場合

unsupported_plugin_version

原因

Updaterプラグインのバージョンが古いため、現在のバックエンド要件を満たしていません。

修正

• アップグレード @capgo/capacitor-updater.
• 実行する npx cap sync.
• Native Buildを再構築して再インストールしてください。

disabled_platform_ios / disabled_platform_android

原因

そのプラットフォームでは、チャンネルのアップデートが無効になっています。

修正

• チャンネル設定でプラットフォームのトグルを有効にしてください。

disable_prod_build / disable_dev_build / disable_device / disable_emulator

原因

チャンネルが現在のビルドタイプまたは実行ターゲットを許可していません。

修正

• チャンネル設定をallow_prod, allow_dev, allow_device, allow_emulatorテスト対象に合わせて調整してください。

key_id_mismatch

原因

Bundleの暗号化キーとデバイスキーが一致しません。

修正

• アプリ設定とBundle暗号化ワークフローで、同じ暗号化キー/公開キーを使用してください。

no_channel / null_channel_data

原因

デバイスに対して有効なチャンネルが見つかりませんでした。

修正

• クラウドのデフォルトチャンネルを設定するか、
• 設定済み defaultChannel テストビルドで設定するか、
• デバイスにチャンネルの上書きを割り当ててください。

関連ドキュメント:

• チャネル

on_premise_app

原因

バックエンドが HTTP 429 を返しました on_premise_app。これには3つの原因が考えられます：

1. Capgo に App ID が存在しない — デバイスから app_id 送信された ID が登録されていないため、バックエンドに記録がありません。
2. アプリがオンプレミスとしてフラグ付けされている — アプリ自体は存在しますが、セルフホストのアップデート用に設定されているため、Capgo のクラウドエンドポイントが配信を拒否します。
3. Organization プランが解約されている — アプリの Organization に有効なサブスクリプションがありません。

よくある間違い

タイポ（打ち間違い） plugins.CapacitorUpdater.appId ( capacitor.config.ts) または Capgo ダッシュボードに登録されている App ID との一致しないケース。バックエンドは「不明なアプリ」と「オンプレミスアプリ」を区別できないため、同じエラー code を返します。

修正

• 次を確認： app_id が Capgo ダッシュボードの表示と完全に一致していること（大文字・小文字を区別）。
• アプリがまだ登録されていない場合は、次を実行してください： npx @capgo/cli@latest app add.
• アプリを意図的にオンプレミスで運用している場合は、 plugins.CapacitorUpdater.updateUrl を Capgo のクラウドURLではなく、セルフホストのアップデートエンドポイントに設定してください。
• Organizationプランが期限切れの場合は、更新またはアップグレードしてください。

クイック診断チェックリスト

1. ビルドに合った app ID と channel であることを確認してください。
2. 確認： CapacitorUpdater.version がインストール済みのネイティブアプリのバージョンと一致していること。
3. チャンネルポリシー（disable_auto_update）が意図したロールアウトと一致しているか確認してください。
4. プラットフォーム/ビルドターゲットの切り替え設定で、このデバイスが許可されているか確認してください。
5. 実行する npx @capgo/cli@latest app debug また、バックエンドのエラー code を確認してください。

さらにサポートが必要ですか？

• トラブルシューティング
• サポートを受ける方法

アップデートに関する一般的な問題から次へ

以下を使用している場合： よくあるアップデートの問題 ネイティブプラグインの作業を計画するには、それを以下と連携させる @capgo/capacitor-updater の使い方 @capgo/capacitor-updater を使用する場合のネイティブ機能について、 Capgo プラグインディレクトリ Capgo プラグインディレクトリでのプロダクトワークフロー向けに、 Capgo による Capacitor プラグイン Capgo による Capacitor プラグインの実装詳細については、 プラグインの追加・更新 実装の詳細は Adding or Updating Plugins を、 Ionic Enterprise プラグインの代替案 製品ワークフローは Ionic Enterprise Plugin Alternatives を参照してください。