PKR-Lab

Debugging und Fehlersuche

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ios/debugging.md

Debugging und Fehlersuche

Zentrale Seite für die iOS-App. Funktionsspezifisches steht auf den Seiten Übersicht und Alerts, Steuerung, Alltag-Modus und Verbindung und Sicherheit. Das projektübergreifende Kapitel ist die zentrale Fehlersuche. Das Backend hat eine eigene Fehlerbehebung.


Wie die App Fehler behandelt


Fehlermeldungen aus dem Code

Verbindung zu carplay-api und WoL-Agent

Meldung Ursache Lösung
Server antwortete mit HTTP <n> Statuscode außerhalb 200–299 ohne error im Body Code deuten: 401 Token, 403 Allowlist, 429 Rate-Limit, 502 power-agent, 503 fehlendes Secret (carplay-api)
<Text des Servers> (aus JSON {"error": "…"}) Backend lehnt die Anfrage ab, zum Beispiel falscher Bestätigungscode Text lesen, Ursache im Backend (Steuerung)
Antwort konnte nicht gelesen werden: <Detail> Antwort ist kein erwartetes JSON (anderer Typ) Antwort mit curl prüfen, App und Backend-Version abgleichen
Kein Token im Schlüsselbund gespeichert, bitte in den Einstellungen eintragen. Token von carplay-api bzw. des WoL-Agents fehlt; die App sendet dann keine Anfrage Einstellungen → carplay-api Token bzw. Vereinsheim-WoL-Agent-Token
Server antwortete mit HTTP 401 Token von carplay-api falsch Einstellungen → carplay-api Token
Schlüsselbund-Fehler: <Text> Lesen, Speichern oder Löschen im Keychain scheiterte (z. B. Gerät gesperrt) Gerät entsperren, erneut versuchen
iOS-Systemtext „cancelled“ / „abgebrochen“ Pinning lehnt das Zertifikat ab Verbindung und Sicherheit
iOS-Systemtext „The request timed out.“ kein Antwort in 10 Sekunden VPN, Netz, Cluster prüfen
iOS-Systemtext „A server with the specified hostname could not be found.“ Name nicht auflösbar Tailscale, DNS
iOS-Systemtext „Could not connect to the server.“ Host erreichbar, aber Port geschlossen oder Dienst down Backend-Pod prüfen (kubectl -n carplay-api get pods)

Alltag-Modus

Meldung Ursache Lösung
Wetter konnte nicht geladen werden. Open-Meteo antwortete nicht mit 200 Alltag-Modus
Pegelstand konnte nicht geladen werden. Pegelonline nicht erreichbar wie oben
Kein Tankerkönig-API-Key hinterlegt — in den Einstellungen ergänzen. Key fehlt Einstellungen
Tankerkönig antwortete mit HTTP <n>. HTTP-Fehler der API Key und Nutzungslimits prüfen
Antwort von Tankerkönig konnte nicht gelesen werden. Formatänderung FuelModels.swift
Tankpreise konnten nicht geladen werden., Tankstellen in der Nähe konnten nicht geladen werden. API meldete ok: false ohne Text Key prüfen
Keine passende Station im Umkreis von 10 km gefunden. nur ausgeschlossene Marken Constants.swift
Standortzugriff wurde nicht erlaubt — in den iOS-Einstellungen für diese App aktivieren. Standort abgelehnt iOS-Einstellungen
Nicht verfügbar Nachrichtenquelle nicht lesbar curl auf die Quelle

Einstellungen

Meldung Ursache Lösung
Speichern fehlgeschlagen: <Detail> Keychain verweigert (KeychainError.unhandled(status)) Gerät entsperren, OSStatus nachschlagen
Es ist bereits ein Token gespeichert. / … ein Key … Hinweis, kein Fehler Speichern überschreibt

Checkliste „Feature funktioniert nicht“

  1. Welcher Modus? Alltag braucht nur Internet (und den Tankerkönig-Key), PKR-Lab braucht Heimnetz oder Tailscale.
  2. Netz: Tailscale auf dem Gerät aktiv? https://carplay-api.prod.homeserver/health in Safari lädt? (Safari nutzt den System-Trust. Ein Zertifikatsfehler dort ist auch ein Hinweis für die App.)
  3. Token: Einstellungen → „Es ist bereits ein Token gespeichert.“ Steht dort nichts, Token neu eintragen. Der Wert muss dem Klartext des SealedSecrets entsprechen.
  4. Backend direkt:
    curl --cacert pki/homeserver-root-ca.pem -H "Authorization: Bearer <TOKEN>" https://carplay-api.prod.homeserver/api/dashboard
    
    200 mit JSON: App-Problem. Fehler: Backend-Problem.
  5. Backend-Logs: kubectl -n carplay-api logs deploy/carplay-api --tail=100 (strukturierte JSON-Zeilen mit Methode, Pfad, Status, Dauer, ohne Header).
  6. Zertifikat: openssl s_client -connect carplay-api.prod.homeserver:443 -CAfile pki/homeserver-root-ca.pem -verify_return_error </dev/null. Muss Verify return code: 0 (ok) zeigen.
  7. Bundle-CA: Resources/homeserver-root-ca.pem entspricht pki/homeserver-root-ca.pem in capulus-core und läuft nicht ab.
  8. power-agent (nur Steuerung): systemctl status power-agent und journalctl -u power-agent -f auf dem Homeserver (Rolle power_agent).
  9. Neu bauen: Hilft nach Änderungen an Constants.swift oder der Root-CA. Das Projekt zuvor mit xcodegen generate neu erzeugen.

In Xcode debuggen


Typische Probleme zwischen den Repos

Symptom Ursache Lösung
Dashboard leer, App läuft Backend-Konfiguration (config.hosts, Uptime-Kuma-Slug) carplay-api: Fehlerbehebung
Nach Rotation des ArgoCD-Passworts schlägt der Homeserver-Shutdown mit 401 fehl secrets.shutdownConfirmationCode nicht mit erneuert Secrets-Rotation, carplay-api
Root-CA wurde in capulus-core getauscht, App meldet Verbindungsfehler App enthält alte CA, CI ca-checksum ist rot neue Datei kopieren, App neu bauen, Internes TLS
Neuer Host soll in der App erscheinen Host fehlt in config.hosts des Backends Helm-Values von carplay-api
Updates-Karte ist leer github-release-watcher hat die ConfigMap nicht geschrieben github-release-watcher
WoL für das Vereinsheim scheitert Agent oder Token auf dem Banana Pi, Router-WoL Alarmmonitor, banana_pi_kiosk
Dienste-Kacheln öffnen nichts Host im Browser nicht auflösbar DNS und Root-CA im Browser des Geräts
Build schlägt in der CI fehl xcodegen oder xcodebuild siehe Entwicklung

Allgemeines Vorgehen, wenn nichts hilft: Backend per curl prüfen, dann Zertifikat, dann Token. In dieser Reihenfolge sind die Ursachen von außen nach innen eingegrenzt.