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
- Es gibt keine Logs in der App: kein
print, keinos.Logger, kein Debug-Schalter. Es gibt kein Log-Level, das man hochdrehen könnte. - Fehler werden je Ansicht als rote Zeile angezeigt (Steuerung, Alltag-Modus, Einstellungen). Die Übersicht zeigt den Fehlertext im gelben Hinweis „Homeserver nicht erreichbar …“, Fehler der Update-Liste stehen in der Karte „Updates“.
- Der Fehlertext stammt aus
LocalizedError.errorDescriptionder eigenen Typen oder aus dem Systemtext vonURLError. - Unbekannte oder fehlende Werte werden tolerant behandelt (Alert-Stufe →
info, Monitor-Status →unknown, fehlende Listen → leer, fehlende Felder einzelner Einträge → Standardwerte). Das Decodieren scheitert nur noch bei falschen Typen.
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“
- Welcher Modus? Alltag braucht nur Internet (und den Tankerkönig-Key), PKR-Lab braucht Heimnetz oder Tailscale.
- Netz: Tailscale auf dem Gerät aktiv?
https://carplay-api.prod.homeserver/healthin Safari lädt? (Safari nutzt den System-Trust. Ein Zertifikatsfehler dort ist auch ein Hinweis für die App.) - Token: Einstellungen → „Es ist bereits ein Token gespeichert.“ Steht dort nichts, Token neu eintragen. Der Wert muss dem Klartext des SealedSecrets entsprechen.
- Backend direkt:
curl --cacert pki/homeserver-root-ca.pem -H "Authorization: Bearer <TOKEN>" https://carplay-api.prod.homeserver/api/dashboard200mit JSON: App-Problem. Fehler: Backend-Problem. - Backend-Logs:
kubectl -n carplay-api logs deploy/carplay-api --tail=100(strukturierte JSON-Zeilen mit Methode, Pfad, Status, Dauer, ohne Header). - Zertifikat:
openssl s_client -connect carplay-api.prod.homeserver:443 -CAfile pki/homeserver-root-ca.pem -verify_return_error </dev/null. MussVerify return code: 0 (ok)zeigen. - Bundle-CA:
Resources/homeserver-root-ca.pementsprichtpki/homeserver-root-ca.pemin capulus-core und läuft nicht ab. - power-agent (nur Steuerung):
systemctl status power-agentundjournalctl -u power-agent -fauf dem Homeserver (Rolle power_agent). - Neu bauen: Hilft nach Änderungen an
Constants.swiftoder der Root-CA. Das Projekt zuvor mitxcodegen generateneu erzeugen.
In Xcode debuggen
- Fehlerursache der Übersicht lesen: Haltepunkt in
DashboardViewModel.fetchDashboard()imcatch-Block. Dort steht der Fehler (Variableerror) mit Domäne und Code. Der Wertself.errorwird sonst nirgends angezeigt. - HTTP-Verkehr: Haltepunkt in
HomeserverAPIClient.request(...)nach demawait, Variableresponsezeigt den Statuscode,dataden Body mit demerror-Text. Mitpo String(data: data, encoding: .utf8)im Debugger-Fenster lesbar. - TLS-Pinning: Haltepunkt in
MTLSDelegate.urlSession(_:didReceive:completionHandler:). Dort sieht manspace.host, obrootCertificatenilist und das Ergebnis vonSecTrustEvaluateWithError(Variableerror). - Simulator oder Gerät: Der Simulator nutzt das Netz des Macs, nicht das Tailnet des iPhones. Tests gegen den Homeserver gehören auf ein Gerät mit Tailscale.
- Konsole: Die App schreibt keine eigenen Logzeilen. Systemmeldungen zu Netzwerk und Zertifikaten stehen in der Xcode-Konsole oder in der Konsole-App des Macs (Gerät auswählen, nach dem Prozessnamen filtern).
- Keychain zurücksetzen: App vom Gerät löschen und neu installieren. TODO: prüfen, ob Keychain-Einträge nach Deinstallation erhalten bleiben (iOS-Standard ist, dass sie bleiben können). Alternativ in den Einstellungen die Einträge entfernen.
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.