Häufige Update-Probleme

Wenn ein Update-Check fehlschlägt, gibt Capgo in der Regel einen error code und einen message im /updates Response zurück. Diese Seite erklärt die häufigsten Fehler und die schnellsten Lösungen.

Zuerst lesen

• no_new_version_available ist ein normaler Zustand, kein Fehler.
• Viele Meldungen wie „Update gefunden, aber nicht angewendet“ sind keine Cache-Verzögerungen, sondern Ablehnungen durch Policy oder Konfiguration – besonders wenn die Antwort ein explizites error code.
• Nutzt npx @capgo/cli@latest app debug während der Reproduktion des Problems, um Request- und Response-Details zu sehen.

Häufige Fehlercodes

provider_infrastructure_request_blocked

Ursache

Die App hat Provider-Infrastruktur-Anfragen blockieren aktiviert und der Request von einer bekannten Google- oder Apple-Datacenter-IP-Range stammt. Capgo blockiert diese Requests auf /updates, /stats, und /channel_self damit Traffic von Providern nicht als Gerätetraffic gewertet wird.

Lösung

• Reproduziere das Update auf einem physischen Gerät in einem normalen Nutzernetzwerk.
• Verwenden Sie keine cloudbasierten Probes oder Datacenter-Runner von Providern für Updater-, Stats- oder Channel-Self-Checks, solange dieser Schutz aktiviert ist.
• Falls dieser Traffic beabsichtigt ist, öffne den Informationen -Tab und deaktiviere Provider-Infrastruktur-Anfragen blockieren. Aktiviere es wieder, sobald der Test abgeschlossen ist.

Bei neuen Apps ist dieser Schutz standardmäßig aktiviert. Apps, die vor dieser Einstellung erstellt wurden, behalten sie deaktiviert, bis du sie manuell einschaltest.

Response-Details

• /updates behält den Updater-Response-Contract bei und gibt HTTP zurück 200. Der Body enthält error, message, kind: "blocked", und provider ("google" oder "apple").
• /stats und /channel_self HTTP zurückgeben 429 mit demselben Fehler code. Betrachte dies als absichtliche Richtlinienblockierung und nicht als vorübergehenden Retry-Zustand.

disable_auto_update_to_major

Ursache

Dein Channel blockiert Major-Upgrades (disable_auto_update = major) und die Major-Version des Ziel-Bundles liegt über der Basisversion des Geräts.

Typisches Symptom

version: 1.0.8 mit old: 0.0.0 bedeutet, dass das Gerät die Baseline meldet 0.0.0, daher werden Major-Upgrades abgelehnt.

Interpretation

Das Backend vergleicht die Major-Versionen anhand der Device-Baseline old und des Targets version.

• Wenn das Target 1.0.1ist, muss die Baseline-Major-Version 1 sein (zum Beispiel 1.0.0).
• Wenn das Target 10.0.1ist, muss die Baseline-Major-Version 10 sein (zum Beispiel 10.0.0).

Lösung A (empfohlen): Device-Baseline-Major anpassen

Setzen Sie plugins.CapacitorUpdater.version in einem capacitor.config.* also MAJOR entspricht der MAJOR-Version des Bundles, das du ausliefern möchtest (z. B. 1.0.0 für 1.0.1, 10.0.0 für 10.0.1).

Wende diese Konfiguration einmalig auf die installierte App an:

1. Ausführen npx cap sync.
2. Baue die native App neu und installiere sie erneut.

Lösung B: Kanalrichtlinie lockern

Auto-Updates über Major-Versionen hinweg in den Kanaleinstellungen erlauben (nur wenn diese Rollout-Strategie gewollt ist).

Verwandte Dokumente:

• Version Targeting: Auto-Updates über Major-Versionen hinweg deaktivieren
• Channels: Auto-Update-Strategien deaktivieren

disable_auto_update_to_minor / disable_auto_update_to_patch

Ursache

Die Channel-Policy ist strenger (minor oder patch) als das angebotene Update.

• minor blockiert, wenn das Ziel-Bundle eine andere Major- oder Minor-Version als die native Baseline des Geräts hat (version_build). Beispiel: 1.2.3 -> 1.3.0 wird blockiert.
• patch blockiert jede Änderung der Major-, Minor- oder Patch-Nummer von version_build. Es sind nur Suffix-Änderungen erlaubt, während MAJOR.MINOR.PATCH identisch bleibt, wie zum Beispiel 1.0.0-beta.1 -> 1.0.0-beta.2 oder 1.0.0+build.1 -> 1.0.0+build.2.

Lösung

• Lade ein Bundle hoch, das mit der aktuellen Policy kompatibel ist, oder
• ändere die Channel-Policy im Dashboard/CLI.

Verwandte Dokumente:

• Channels: Auto-Update-Strategien deaktivieren

disable_auto_update_to_metadata

Ursache

Channel nutzt Metadata-basiertes Targeting (version_number) und die Device-Baseline liegt unter dem erforderlichen min_update_version.

Lösung

• Geräte-Baseline (CapacitorUpdater.version) mit der installierten Native-App-Version abgleichen oder
• anpassen min_update_version / Channel-Strategie.

Verwandte Dokumente:

• Channels: Auto-Update-Strategien deaktivieren

disable_auto_update_under_native

Ursache

Channel verhindert Downgrades unterhalb der Native-Baseline.

Lösung

• Lade eine Bundle-Version hoch, die größer oder gleich der nativen Baseline ist, oder
• deaktiviere den Downgrade-Schutz „under native“ für diesen Channel.

Verwandte Dokumente:

• Version Targeting: Auto-Downgrade-Schutz

cannot_update_via_private_channel

Ursache

Der ausgewählte/Standard-Channel erlaubt kein Self-Assignment für Geräte.

Lösung

• Nutze einen anderen Channel mit aktiviertem Self-Assignment, oder
• mache den Channel öffentlich / aktiviere Self-Assignment.

Verwandte Dokumente:

• Channels: Verwendung von setChannel() in deiner App

unknown_version_build / semver_error

Ursache

Die Baseline-Version des Geräts fehlt (unknown) oder ist nicht gültiges Semver.

Lösung

• Setzen Sie plugins.CapacitorUpdater.version an einen gültiges Semver wie 1.2.3.
• Synchronisieren und native App neu bauen.

Verwandte Dokumente:

• Kanäle: Bundle-Versionierung und Kanäle
• Fehlerbehebung: Updates werden nicht angewendet

unsupported_plugin_version

Ursache

Die Updater-Plugin-Version ist zu alt für die aktuellen Backend-Anforderungen.

Lösung

• Upgrade @capgo/capacitor-updater.
• Ausführen npx cap sync.
• Native App neu bauen und neu installieren.

disabled_platform_ios / disabled_platform_android

Ursache

Für diese Plattform sind Updates im Channel deaktiviert.

Lösung

• Plattformumschalter im Channel aktivieren.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

Ursache

Channel erlaubt aktuellen Build-Typ oder Runtime-Ziel nicht.

Lösung

• Channel-Optionen (allow_prod, allow_dev, allow_device, allow_emulator) an Ihr Testziel anpassen.

key_id_mismatch

Ursache

Bundle encryption key and device key differ.

Lösung

• Verwende denselben Verschlüsselungs-/öffentlichen Schlüssel in der App-Konfiguration und im Bundle-Verschlüsselungs-Workflow.

no_channel / null_channel_data

Ursache

Für das Gerät konnte kein gültiger Channel gefunden werden.

Lösung

• Setze einen Cloud-Default-Channel oder
• Setzen defaultChannel in Test-Builds oder
• weise dem Gerät einen Channel-Override zu.

Verwandte Dokumente:

• Kanäle

on_premise_app

Ursache

Das Backend hat HTTP 429 zurückgegeben mit on_premise_app. Dies tritt in drei Situationen auf:

1. App-ID existiert nicht in Capgo — die app_id vom Gerät gesendete ID ist nicht registriert, daher hat das Backend keinen Eintrag dafür.
2. App ist als On-Premise markiert — die App existiert, ist aber für selbst gehostete Updates konfiguriert, daher lehnt der Capgo-Cloud-Endpunkt die Bereitstellung ab.
3. Organisationsplan wurde gekündigt — die Organisation der App hat kein aktives Abo mehr.

Häufiger Fehler

Ein Tippfehler in plugins.CapacitorUpdater.appId (in capacitor.config.ts) oder eine Abweichung von der im Capgo-Dashboard registrierten App-ID. Das Backend kann „unbekannte App“ nicht von „On-Premise-App“ unterscheiden und gibt daher denselben Fehler code zurück.

Lösung

• Prüfen Sie, ob der app_id entspricht exakt dem, was im Capgo-Dashboard angezeigt wird (Groß-/Kleinschreibung beachten).
• Falls die App noch nicht registriert ist, führe aus npx @capgo/cli@latest app add.
• Falls die App bewusst on-premise läuft, setze plugins.CapacitorUpdater.updateUrl auf deinen selbst gehosteten Update-Endpunkt anstelle der Capgo-Cloud-URL.
• Falls der Organisationsplan abgelaufen ist, verlängere oder upgrade den Plan.

Schnelle Diagnose-Checkliste

1. Prüfe, ob App-ID und Channel für den Build korrekt sind.
2. Bestätigen CapacitorUpdater.version entspricht der installierten nativen App-Version.
3. Channel-Policy prüfen (disable_auto_update) entspricht der geplanten Auslieferung.
4. Plattform-/Build-Ziel-Schalter erlauben dieses Gerät.
5. Ausführen npx @capgo/cli@latest app debug und Backend-Fehler code lesen.

Mehr Hilfe nötig?

• Fehlerbehebung
• Support erhalten

Weiter zu Häufigen Update-Problemen

Wenn du es nutzt Häufige Update-Probleme Um die Arbeit an nativen Plugins zu planen, verbinde sie mit Verwendung von @capgo/capacitor-updater für die native Funktion in der Verwendung von @capgo/capacitor-updater, Capgo Plugin-Verzeichnis für den Produkt-Workflow im Capgo Plugin-Verzeichnis, Capacitor Plugins von Capgo für das Implementierungsdetail in Capacitor Plugins von Capgo, Plugins hinzufügen oder aktualisieren für das Implementierungsdetail beim Hinzufügen oder Aktualisieren von Plugins, und Ionic Enterprise Plugin-Alternativen für den Produkt-Workflow bei den Ionic Enterprise Plugin-Alternativen.