Common Update Problems

更新チェックが失敗した場合、Capgoは通常 error codeと message の /updates レスポンスを返します。このページでは、最も一般的なエラーと最速の修正方法を説明します。

最初に読むこと

• no_new_version_available 正常状態であり、エラーではない。
• 多くの「更新が見つかったが適用されなかった」報告は、キャッシュの遅延ではなく、特に応答に明示的な error code
• 使用 npx @capgo/cli@latest app debug 問題を再現する際にリクエスト/レスポンスの詳細を確認するには

一般的なエラー コード

disable_auto_update_to_major

原因

チャネルがメジャーアップグレードをブロックし（）、およびデバイスのベースライン バージョンより上のターゲット バンドルのメジャー バージョンがあります。disable_auto_update = major典型的な症状

Common failure codes

version: 1.0.8 with old: 0.0.0 は、デバイスがベースラインを報告することを意味します。 0.0.0なぜなら、デバイスがベースラインを報告することは、

How to interpret it

バックエンドは、デバイスのベースラインのメジャーバージョンとターゲットのメジャーバージョンを比較します。 old ターゲットが version.

• の場合、ベースラインのメジャーバージョンは 1.0.1の場合、ベースラインのメジャーバージョンは 1 の場合、ベースラインのメジャーバージョンは 1.0.0).
• の場合、ベースラインのメジャーバージョンは 10.0.1の場合、ベースラインのメジャーバージョンは 10 の場合、ベースラインのメジャーバージョンは 10.0.0).

オプション A (推奨): デバイスの基準線をメジャーに合わせる

セット plugins.CapacitorUpdater.version その capacitor.config.* メジャー bundle のメジャーと一致するように設定してください (例えば、 の 1.0.0 の 1.0.1, 10.0.0 その後、インストール済みのアプリにこの設定を適用してください: 10.0.1).

実行

1. ネイティブ アプリを再構築して再インストールしてください。 npx cap sync.
2. オプション B: チャネル ポリシーを緩和する

__CAPGO_KEEP_0__

メジャー間のクロスアップデートをチャンネル設定で許可する (ロールアウト戦略が意図的である場合のみ)。

関連ドキュメント:

• バージョン対象設定: メジャーバージョン間で自動更新を無効にする
• チャンネル: 自動更新戦略を無効にする

disable_auto_update_to_minor / disable_auto_update_to_patch

原因

チャンネルポリシーは、提供されているアップデートよりも厳密 (minor または patch) です。

• minor ターゲットバンドルのメジャーまたはマイナーバージョンがデバイスのネイティブベースラインと異なる場合、ブロックされます (version_build). 例: 1.2.3 -> 1.3.0 ブロックされます。
• patch メジャー、ミニマム、パッチ番号の変更をブロックします。 version_buildスUFFIX の変更のみ許可されます。 MAJOR.MINOR.PATCH そのまま残ります。例えば、 1.0.0-beta.1 -> 1.0.0-beta.2 または 1.0.0+build.1 -> 1.0.0+build.2.

現在のポリシーに適合するバンドルをアップロードするか、

• __CAPGO_KEEP_0__ でのダッシュボードでチャネル ポリシーを変更する。
• change channel policy in dashboard/CLI.

チャネル：Auto Update ストラテジーを無効にする

• セクション “disable_auto_update_to_metadata”

disable_auto_update_to_metadata

チャネルはメタデータベースのターゲットを使用しています

Channel uses metadata-based targeting (version_numberとデバイスの基準値は、必要な値より下です。 min_update_version.

修正

• インストール済みのネイティブアプリのバージョンとデバイスの基準値を合わせる、またはCapacitorUpdater.version調整
• / チャネル戦略。 min_update_version 関連ドキュメント:

チャンネル: Auto Update戦略を無効にする

• セクションのタイトル “disable_auto_update_under_native”

disable_auto_update_under_native

チャネルはネイティブの基準値以下のダウングレードを防ぎます。

修正

__CAPGO_KEEP_0__

• アップロードするバンドルバージョンは、ネイティブベースライン以上でなければなりません、または
• そのチャンネルで「ネイティブ」ダウングレード保護を無効にします。

関連ドキュメント：

• バージョン対象設定：自動ダウングレード防止

cannot_update_via_private_channel

原因

選択中/デフォルトのチャンネルは、デバイスの自己割り当てを許可していません。

修正

• 異なるチャンネルを使用して、自己割り当てを有効にします、または
• チャンネルを公開/自己割り当てを有効にします。

関連ドキュメント：

• チャンネル：setChannel()を使用するアプリ

unknown_version_build / semver_error

原因

デバイスのベースラインバージョンが欠落している (unknown) または不正な semver 修正.

を

• 有効な semver plugins.CapacitorUpdater.version に設定します 例えば ネイティブアプリをSyncし、再構築します。 1.2.3.
• 関連ドキュメント:

Related docs:

• チャンネル: バンドルバージョニングとチャンネル
• トラブルシューティング: アップデートが適用されない

unsupported_plugin_version

原因

__CAPGO_KEEP_0__バックエンドの要件に対応していないため、アップデート プラグインのバージョンが古いです。

修正

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

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

原因

バンドル暗号化キーとデバイスキーが異なります。

修正

• 同じ暗号化キー/公開鍵をアプリ設定とバンドル暗号化ワークフローで使用します。

no_channel / null_channel_data

原因

デバイスに有効なチャネルが解決されませんでした。

修正

• デフォルトのクラウドチャネルを設定するか、
• テストビルドの場合、または defaultChannel デバイスにチャネルオーバーライドを割り当てる。
• 関連ドキュメント：

チャネル

• セクション「on_premise_app」

on_premise_app

原因

バックエンドからHTTP 429が返されました。 on_premise_appこれは3つの状況で発生します。

1. App IDがCapgoに存在しない場合 — デバイスから送信された app_id は登録されていないため、バックエンドにはその記録がない。
2. アプリがオンプレミスとしてマークされている — アプリが存在するが、自社ホストの更新設定になっているため、Capgoのクラウドエンドポイントはそれを提供しない。
3. 組織のプランがキャンセルされた — アプリの組織が有効なサブスクリプションを持っていないため。

よくある間違い

タイプミス plugins.CapacitorUpdater.appId (in capacitor.config.ts) or a mismatch with the app ID registered in the Capgo dashboard. The backend cannot distinguish “unknown app” from “on-premise app”, so it returns the same error code.

Fix

• を確認してください。 app_id matches exactly what is shown in the Capgo dashboard (case-sensitive).
• がダッシュボードに表示されているものと完全に一致していることを確認してください (大文字小文字を区別します)。 npx @capgo/cli@latest app add.
• If the app is not registered yet, run plugins.CapacitorUpdater.updateUrl to your self-hosted update endpoint instead of the Capgo cloud URL.
• をあなたの自社の更新エンドポイントに置き換えてください。

If the organization plan expired, renew or upgrade the plan.

1. セクションのタイトルは “Quick diagnostic checklist” です。
2. 確認 CapacitorUpdater.version __CAPGO_KEEP_0__がインストール済みのネイティブアプリのバージョンと一致します。
3. 確認チャンネルポリシー（disable_auto_update）が意図されたロールアウトと一致します。
4. 確認プラットフォーム/ビルドターゲットのスイッチがこのデバイスに許可します。
5. 実行 npx @capgo/cli@latest app debug バックエンドエラーを読み取ります：code。

さらに助けが必要ですか？

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

一般的なアップデートの問題から続けてください

Capgoを使用している場合 Common Update Problems nativeプラグインの作業を計画するには、__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-updaterと接続します native capabilityのcapgo=capacitor-updaterを使用します for the native capability in Using @capgo/capacitor-updater, product workflowのCapgo Plugin Directoryを使用します Capgo Plugins by __CAPGO_KEEP_1__ Capacitor Plugins by Capgoの実装詳細を確認します for the implementation detail in Capacitor Plugins by Capgo, Adding or Updating Pluginsの実装詳細を確認します __CAPGO_KEEP_0__ Plugin Directoryの__CAPGO_KEEP_1__を使用します Ionic Enterprise Plugin Alternatives Ionic Enterprise プラグイン代替