Troubleshooting

Erste Diagnose

Führe die projektbezogenen Commands im Projektordner aus. doctor prüft lokale Tools, Docker und Gateway-Zustand sowie im geladenen Projekt konfigurierte HTTP-Routen. Für die Routenprüfung sollte die Umgebung laufen; ein gestopptes Projekt kann entsprechend als nicht erreichbar erscheinen.

• Notiere den fehlgeschlagenen Command und die erste konkrete Diagnose.
• Prüfe Voraussetzungen vor dem Start und Runtime-Status nach dem Start getrennt.
• Ändere gezielt eine Ursache und prüfe danach erneut.

dwell doctor

Vor dem Start prüfen

plan up zeigt geplante Schritte und beobachtete Blocker, ohne Dateien zu erzeugen oder Services zu starten. Behebe gemeldete Voraussetzungen vor dem nächsten dwell up.

dwell plan up

Ein erfolgreicher Plan reserviert keine Ports und garantiert keinen späteren erfolgreichen Start. Er deckt nicht sämtliche Runtime- und Anwendungsfehler ab.

Status und Logs

ps zeigt Rollen, Prozesse, Compose-Status und URLs einschließlich LAN-Status. logs listet vorhandene Dwell-Logs; ohne solche Logs kann es bei Backend-Projekten Compose-Ausgabe zeigen. Wähle anschließend das zum Fehler passende Log.

dwell ps

dwell logs

Beispiele sind dwell logs build, dwell logs compose, dwell logs frontend und dwell logs gateway. Gezielte Dwell-Logs folgen der Ausgabe und brauchen das lokale tail-Werkzeug. Beende das Folgen mit Ctrl+C. Logs können Anwendungs-Secrets enthalten; prüfe sie vor dem Teilen.

Docker läuft nicht

Symptom: Der Start meldet einen nicht erreichbaren Docker-Daemon oder fehlende Compose-Voraussetzungen.

Prüfe zuerst, ob Docker Desktop oder Docker Engine läuft. Verwende Linux-Container; auch reine Frontend-Projekte brauchen Docker für das gemeinsame Gateway.

dwell doctor

Behebe die von doctor gemeldeten Docker-/Compose-Probleme, wiederhole plan up und starte danach mit dwell up.

Port ist belegt

Symptom: Gateway oder Frontend können nicht an einem Port starten, oder die ausgegebene URL enthält einen höheren Port.

Prüfe mit plan up den Port-Befund. Ist nur Port 80 belegt, kann Dwell auf einen freien hohen Gateway-Port ausweichen; das ist nicht automatisch ein Fehler. Nutze die ausgegebene URL.

dwell plan up

Bei einem tatsächlichen Konflikt identifiziere den belegenden Prozess und entscheide bewusst, ob du ihn stoppen kannst. Für Frontend-Konflikte lies zusätzlich dwell logs frontend; für das Gateway dwell logs gateway.

Frontend startet nicht

Symptom: Backend oder Gateway laufen, aber der Frontend-Prozess startet nicht oder beendet sich sofort.

Prüfe ps und das Frontend-Log: Abhängigkeiten, Node-Version, Start-Command und Anwendungsfehler sind typische Ursachen. Ein Custom-Frontend braucht einen gültigen konfigurierten Start-Command.

dwell logs frontend

Behebe den konkreten Fehler im Frontend. Nutze dwell build zum Vorbereiten der Abhängigkeiten und danach dwell up; ändere keine Framework-Version allein auf Verdacht.

Domain nicht erreichbar

Symptom: Die lokale .localhost-Adresse ist nicht erreichbar oder liefert eine unerwartete Seite.

Prüfe mit ps, ob das Projekt läuft, und mit access die konfigurierte URL inklusive Port. routing list zeigt Host und Pfad; access allein prüft keine Erreichbarkeit.

dwell logs gateway

Prüfe die konfigurierte Route mit doctor und lies das Gateway-Log. Eigene Domains außerhalb .localhost brauchen eigene Namensauflösung. Nach einem physischen Projektumzug nutze reinit wie im Workflow-Guide.

HTTPS nicht vertraut

Symptom: HTTP funktioniert, aber der Browser vertraut dem HTTPS-Zertifikat nicht.

Prüfe Hostname, ausgegebenen HTTPS-Status und das Vertrauen in die mkcert-CA auf genau diesem Gerät. doctor zeigt mkcert- und Gateway-Informationen; die HTTP-Routenprüfung bestätigt kein Zertifikatsvertrauen.

dwell doctor

Richte Zertifikatsvertrauen anhand der mkcert-Anleitung im Netzwerk-Guide ein. Auf einem weiteren Gerät ist das ein eigener Schritt. Ersetze eine Vertrauensprüfung nicht durch dauerhaftes Ignorieren der Browserwarnung.

LAN nicht erreichbar

Symptom: Lokal läuft die Anwendung, aber das Handy erreicht die .local-Adresse nicht.

Prüfe LAN-Status und die ausgegebene Adresse mit ps. Host und Client brauchen ein gemeinsames erreichbares Netzwerk und mDNS-Unterstützung.

dwell ps

Prüfe Interface-Auswahl, Firewall, VPN und WLAN-Isolation mit dem Netzwerk-Guide. up kann lokal erfolgreich sein und LAN-Fehler separat melden; teste immer auf dem tatsächlichen Client.

Node, PHP oder Stack inkompatibel

Symptom: Dwell meldet eine nicht unterstützte Node-Version, PHP-Version oder Stack-Kombination.

Prüfe den installierten Node-Stand und die Projektkonfiguration. versions list zeigt unterstützte Linien und kompatible PHP-Versionen. Ein Frontend kann mehr Node verlangen als die CLI selbst.

dwell versions list

Gleiche Konfiguration und lokale Voraussetzungen mit dem Stack-Guide ab. Stack-Änderungen sind kein Framework-Upgrade und migrieren deinen Anwendungscode nicht.

Hinweise & Grenzen

doctor und plan sind Diagnosehilfen, keine vollständige Anwendungsprüfung. doctor --repair verändert Gateway/Registry und ist nur für einen passenden Zustandsfehler gedacht, nicht als erster Schritt für jedes Problem. Lösche keine Volumes oder Secrets als allgemeine Reparatur. Lass projektändernde Commands fertig laufen, bevor du den nächsten startest.

Als Nächstes

Der Projekte-Guide erklärt den normalen Lifecycle. Für konkrete URL- und Freigabeprobleme helfen Routing und Netzwerk.

Technische Referenz