Fehlerbehebung

Hier findest du häufige Probleme bei der Nutzung von Capgo und wie du sie löst.

🚀 Brauchst du Experten-Hilfe?

Hängst du bei einem komplexen Problem fest? Unser Expertenteam hilft dir gerne! Erhalte persönlichen Support, code Reviews und maßgeschneiderte Lösungen für deine Anforderungen.

Professionellen Support erhalten

Fehler beim Upload

Falls dein Bundle-Upload fehlschlägt, prüfe Folgendes:

• Ob deine App-ID in capacitor.config.ts mit deiner App im Capgo Dashboard übereinstimmt
• Ob du den Upload-Befehl aus dem Root deines Capacitor Projekts ausführst
• Ob deine Web-Assets gebaut und aktuell sind

Erweiterte Upload-Optionen

Das Capgo CLI bietet zusätzliche Flags, um häufige Upload-Probleme zu lösen:

• --tus: Nutzt das das resumable upload Protokoll für zuverlässigere Uploads großer Bundles oder bei schlechter Verbindung. Wenn dein Bundle größer als 10 MB ist oder die Verbindung instabil ist, solltest du --tus:

  npx @capgo/cli@latest bundle upload --tus

• --package-json und --node-modules: Sagt Capgo, wo sich dein Root befindet package.json und node_modules falls deine App eine nicht standardmäßige Struktur wie ein Monorepo oder npm Workspace nutzt. Übergib den Pfad zum Root package.json und den --node_modules Pfad:

  npx @capgo/cli@latest bundle upload --package-json=path/to/package.json --node_modules=path/to/node_modules

  Capgo benötigt diese Informationen, um die Abhängigkeiten deiner App korrekt zu bundlen.

Du kannst diese Flags mit anderen Optionen kombinieren, wie zum Beispiel --channel je nach Bedarf. Siehe die Capgo CLI Dokumentation für alle Details zu den verfügbaren Upload-Optionen.

Falls du weiterhin Probleme beim Upload hast, wende dich an Capgo Support für weitere Unterstützung.

Updates debuggen

Wenn du Probleme mit Live Updates hast, ist der Capgo debug-Befehl ein hilfreiches Tool zur Fehlersuche. So nutzt du ihn:

1. Führe den folgenden Befehl in deinem Projektverzeichnis aus:

   npx @capgo/cli@latest app debug

2. Starte deine App auf einem Gerät oder Emulator und führe die Aktion aus, die ein Update auslösen soll (z. B. das erneute Öffnen der App nach dem Upload eines neuen Bundles).

3. Beobachte die Ausgabe des Debug-Befehls. Er protokolliert Informationen zum Update-Prozess, darunter:

   • Wann die App nach einem Update sucht
   • Ob ein Update gefunden wurde und um welche Version es sich handelt
   • Fortschritt des Downloads und der Installation des Updates
   • Etwaige Fehler, die während des Update-Prozesses auftreten

4. Nutze die Debug-Logs, um die Fehlerquelle zu identifizieren. Zum Beispiel:

   • Falls kein Update gefunden wird, prüfe, ob dein Bundle erfolgreich hochgeladen wurde und die App für den richtigen Channel konfiguriert ist.
   • Falls das Update heruntergeladen, aber nicht installiert wird, stelle sicher, dass du aufgerufen hast CapacitorUpdater.notifyAppReady() und dass die App vollständig geschlossen und neu gestartet wurde.
   • Falls eine Fehlermeldung erscheint, suche nach dem spezifischen Fehler in der Capgo Dokumentation oder kontaktiere den Support für Hilfe.

Der debug-Befehl ist besonders hilfreich, um Probleme beim Download und der Installation des Updates zu finden. Wenn die Logs zeigen, dass die erwartete Version gefunden, aber nicht angewendet wurde, konzentriere die Fehlersuche auf die Schritte nach dem Download.

Debugging mit Native Logs

Zusätzlich zum Capgo debug-Befehl können die Native Logs auf Android, iOS und Electron wertvolle Informationen liefern, besonders bei Problemen auf der nativen Seite des Update-Prozesses.

Android-Logs

So greifst du auf die Android Logs zu:

1. Verbinde dein Gerät oder starte den Emulator
2. Öffne Android Studio und wähle „View > Tool Windows > Logcat“
3. Filtern Sie im Logcat-Fenster die Logs auf den Prozess Ihrer App, indem Sie diesen oben im Dropdown-Menü auswählen
4. Suche nach Zeilen, die Folgendes enthalten: Capgo um die SDK Logs zu finden

Alternativ kannst du den adb logcat Befehl nutzen und nach Capgo filtern, um die Logs einzugrenzen.

Das Capgo SDK protokolliert wichtige Events während des Update-Prozesses, wie zum Beispiel:

• Wenn eine Update-Prüfung gestartet wird
• Ob ein Update gefunden wurde und welche Version es ist
• Wann der Update-Download startet und abgeschlossen ist
• Wann die Installation des Updates ausgelöst wird
• Fehler, die während der Native Build-Schritte auftreten

Häufige Android-spezifische Probleme in den Logs sind:

• Netzwerkprobleme, die den Update-Download verhindern
• Dateiberechtigungsfehler beim Speichern oder Lesen des Update-Bundles
• Nicht genügend Speicherplatz für das Update-Bundle
• App startet nach Installation des Updates nicht neu

iOS-Logs

So greifst du auf die iOS Logs zu:

1. Verbinde dein Gerät oder starte den Simulator
2. Öffne Xcode und gehe zu „Window > Devices and Simulators“
3. Wähle dein Gerät aus und klicke auf „Open Console“
4. Suche in der Console-Ausgabe nach Zeilen, die enthalten Capgo um die SDK Logs zu finden

Du kannst auch den log stream command in the terminal and grep for Capgo um die Logs zu filtern.

Ähnlich wie bei Android werden die Capgo SDK wichtige iOS-seitige Events loggen:

• Start und Ergebnis des Update-Checks
• Download-Start, Fortschritt und Abschluss
• Trigger und Ergebnis der Installation
• Fehler während des Native Build Prozesses

iOS-spezifische Probleme, die in den Logs auftreten können:

• SSL-Zertifikatsprobleme beim Download des Updates
• App Transport Security blockiert den Update-Download
• Nicht genügend Speicherplatz für das Update-Bundle
• Fehler beim Entpacken oder Anwenden des Update-Bundles

Electron-Logs

Prüfe bei Electron-Apps sowohl die Ausgaben des Main- als auch des Renderer-Prozesses:

1. Starte die Electron-App über dein Terminal mit deinem üblichen Startbefehl (zum Beispiel bun run electron:dev oder bun run electron:serve) und beobachte die Terminal-Ausgabe auf Startup-Vorgänge, Update-Checks und Netzwerkfehler.
2. Öffne die DevTools im Renderer-Fenster (View → Toggle Developer Tools) und inspiziere die Console-Logs sowie fehlgeschlagene Netzwerk-Requests, während du den Update-Flow reproduzierst.
3. Prüfe bei paketierten Apps die OS-Log-Tools auf Abstürze oder Startup-Fehler:
   • macOS: öffne Console.app und filtere nach deinem App-Namen
   • Windows: öffnen Event-Viewer → Windows-Protokolle → Anwendung
   • Linux: nutze deinen Desktop-Logviewer oder journalctl für deinen App-Prozess

Beim Debugging von Updates solltest du die Logs des Main-Process und des Renderer-Process vergleichen, um Electron-Bootstrap-Probleme von Capgo Update-Lifecycle-Problemen zu unterscheiden.

Plattformübergreifend bieten die nativen Logs eine detailliertere Ansicht des Update-Prozesses mit mehr Informationen zur nativen Implementierung. Sie sind besonders hilfreich, um Fehler zu finden, die außerhalb der Capgo JavaScript-Schicht auftreten.

Bei der Fehlersuche in komplexen live update Problemen empfiehlt es sich, sowohl die Capgo Debug-Logs als auch die nativen Logs zu erfassen, um ein vollständiges Bild der Situation zu erhalten. Die Kombination beider Logs bietet die beste Chance, das Problem zu identifizieren und zu lösen.

Updates werden nicht angewendet

Falls du ein Bundle hochgeladen hast, die Änderungen aber nicht auf deinem Gerät siehst:

• Stelle sicher, dass du CapacitorUpdater.notifyAppReady() in deiner App code aufgerufen hast, wie in der Quickstart
• Prüfe, ob dein Gerät mit dem Internet verbunden ist und ob die Capgo Debug-Logs den Download des Updates bestätigen
• Schließe die App vollständig und starte sie neu, da Updates erst beim Kaltstart angewendet werden
• Suche in den nativen Logs nach Fehlern, die auf Probleme beim Anwenden des Updates hindeuten könnten

Siehe dazu den Live Update Deployment Guide für Details zum Update-Prozess. Falls das Problem weiterhin besteht, nutze den npx @capgo/cli@latest app debug Befehl und die nativen Logs, um mehr Einblick in den Prozess zu erhalten.

Häufige Fehlercodes bei Updates

Wenn deine Logs Backend-Fehler wie disable_auto_update_to_major, semver_error, oder cannot_update_via_private_channel, nutze den passenden Guide:

• Häufige Update-Probleme

Dort wird erklärt, was die gängigen code bedeuten, warum sie auftreten und wie du sie behebst.

SDK Installation

Wenn du Probleme bei der Installation von Capgo SDK hast, stelle sicher:

• Deine App nutzt eine unterstützte Version von Capacitor (4.0 oder neuer)
• You’ve followed the Quickstart Schritte in der richtigen Reihenfolge, inklusive App-Sync nach der Installation von SDK

CI/CD-Integration

Bei Problemen beim Auslösen von Capgo Uploads aus deiner CI/CD-Pipeline:

• Prüfe, ob dein Capgo Authentication Token korrekt eingerichtet ist
• Stelle sicher, dass du den Upload-Befehl erst nach dem Build deiner Web-Assets ausführst
• Stelle sicher, dass der Upload-Befehl den richtigen Channel-Namen für deine Zielumgebung verwendet

Siehe die CI/CD-Integration Docs für weitere Troubleshooting-Tipps. Du kannst auch den npx @capgo/cli@latest app debug Befehl nutzen, um zu bestätigen, ob deine CI/CD-gesteuerten Updates von der App empfangen werden.

Weiter bei Troubleshooting

Wenn Sie ... verwenden Fehlerbehebung um Speicher und Dateiverarbeitung zu planen, verbinde es mit @capgo/capacitor-data-storage-sqlite für die Implementierungsdetails in @capgo/capacitor-data-storage-sqlite, Verwendung von @capgo/capacitor-data-storage-sqlite für die native Funktion in „Verwendung von @capgo/capacitor-data-storage-sqlite“,“ @capgo/capacitor-file für die Implementierungsdetails in @capgo/capacitor-file, Verwendung von @capgo/capacitor-file für die native Funktion in „Verwendung von @capgo/capacitor-file“, und @capgo/capacitor-uploader für die Implementierungsdetails in @capgo/capacitor-uploader.