For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /de/docs/web/troubleshooting.md (or send Accept: text/markdown).
Fehlerbehebung
Diagnostiziere Einrichtungsprobleme an der tatsächlich fehlgeschlagenen Grenze.
Einrichtung und Konfiguration
Lesen Sie vor jedem Schritt Bevor Sie beginnen und Terminal-Grundlagen. Bei diesen Anweisungen wird davon ausgegangen, dass Sie das vollständige Supastack-Monorepo in VS Code geöffnet haben. Sein Stamm package.json markiert den Repository-Stamm. In pnpm-Befehlen ist ein Arbeitsbereichspaket eine App oder ein Ordner mit gemeinsam genutztem Code. Im Produkt ist ein Arbeitsbereich der Datencontainer und die Sicherheitsgrenze eines Teams. corepack pnpm --filter ... wählt ein Paket aus dem Monorepo aus, während Befehle von seinem Stammverzeichnis aus ausgeführt werden. Wenn Sie nur einen synchronisierten Mobil- oder Desktop-Ordner geöffnet haben, enthält dieser weder das Web-Backend, Docker-Setup noch Root-Skripte: Führen Sie das Backend von diesem Monorepo oder einem erreichbaren gehosteten Server aus und verwenden Sie die eigenen Skripte des Plattformordners. Eine Umgebungsvariable ist eine benannte Einstellung, die in einer lokalen .env-Datei oder Ihrem Hosting-Dashboard gespeichert ist; Starten Sie die entsprechende App neu, nachdem Sie sie geändert haben, und halten Sie Servergeheimnisse von den Werten NEXT_PUBLIC_ und EXPO_PUBLIC_ fern.
1. Kopieren Sie die erste nützliche Fehlerzeile und den Befehl, der sie erzeugt hat. Fügen Sie keine geheimen Werte ein.
2. Führen Sie vom Repository-Root aus corepack pnpm --filter @supastack/web typecheck für Webtypfehler oder corepack pnpm test für die automatisierte Suite aus.
3. Bei einem Browserproblem starten Sie Web mit corepack pnpm --filter @supastack/web dev und reproduzieren es unter http://localhost:3000.. Erwartet: Sie können feststellen, ob der Fehler im Setup, Code, der Datenbank, dem Anbieter oder dem Browser liegt, bevor Sie die Einstellungen ändern.
Lies den fehlgeschlagenen Befehl und den ersten relevanten Fehler, bevor du die Konfiguration änderst. Ermittle, ob Installation von Abhängigkeiten, Kompilierung, Umgebungsvalidierung, Datenbankzugriff, Provider-Aufruf oder Browserverhalten fehlgeschlagen ist.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm --filter @supastack/web build
corepack pnpm testBefehle zum Kopieren
Befolgen Sie die Kommentare, um zu sehen, in welchem Ordner ein Befehl ausgeführt wird. Wenn zwei Terminals gekennzeichnet sind, öffnen Sie zwei Terminalfenster und lassen Sie den ersten Befehl laufen, während Sie den zweiten verwenden.
corepack pnpm --filter @supastack/web typecheck
corepack pnpm testFehler beim ersten Lauf, entschlüsselt
Der erste Lauf schlägt nur auf wenige Arten fehl. Ordnen Sie die erste rote Fehlerzeile einer Tabellenzeile zu — spätere Fehler sind meist Folgen des ersten, beheben Sie also den obersten vor allem anderen.
| Anzeichen | Wahrscheinliche Ursache | Erste Abhilfe |
|---|---|---|
| node, corepack oder pnpm wird nicht erkannt / command not found | Das Werkzeug ist nicht installiert, oder das Terminal war vor Ende der Installation geöffnet | Installieren Sie es (oder öffnen Sie das Terminal erneut) und versuchen Sie dann node --version erneut |
| package.json nicht gefunden / ENOENT package.json | Das Terminal befindet sich im falschen Ordner | Wechseln Sie mit cd in das Repository-Stammverzeichnis — den Ordner, der package.json enthält — und versuchen Sie es erneut |
| EADDRINUSE / Port 3000 ist bereits belegt | Ein anderer Entwicklungsserver hält den Port noch | Finden Sie das Terminal dieses Servers, drücken Sie Strg + C und starten Sie erneut |
| ECONNREFUSED zu localhost:5432 oder ein Datenbankverbindungsfehler | Postgres läuft nicht | Führen Sie docker compose up -d postgres aus, warten Sie auf healthy und versuchen Sie es erneut |
| Umgebungsvalidierungsfehler, der einen fehlenden Schlüssel nennt | apps/web/.env.local fehlt oder enthält einen leeren Pflichtwert | Kopieren Sie den genannten Schlüssel aus .env.example, geben Sie ihm einen Wert, speichern Sie und starten Sie den Server neu |
| corepack oder pnpm fehlt nach corepack enable | Es liegt kein pnpm-Shim auf PATH | Verwenden Sie corepack pnpm ... direkt — es braucht nie einen Shim; unter Windows verwenden Sie corepack.cmd |
| PowerShell meldet, dass ein .ps1-Skript nicht ausgeführt werden kann / blockiert ist | Die Skriptrichtlinie von PowerShell blockiert den Shim | Verwenden Sie die .cmd-Form — corepack.cmd pnpm install — keine Richtlinienänderung nötig |
Implementierungsablauf
Prüfe bei fehlendem API-Zugriff, ob der Server läuft und der konfigurierte Ursprung mit dem Client übereinstimmt. Wenn keine KI-Auswahl verfügbar ist, prüfe AI_MODEL_POLICY und aktivierte Katalogzeilen. Verwende bei einer unsicheren eingereihten Aufgabe den gespeicherten Wiederherstellungsablauf, statt eine weitere Aufgabe einzureichen.
Bei Problemen mit dem Browserlayout prüfe berechnete Stile und reproduziere genau denselben Viewport. Token der Produkt-Chrome liegen in app-theme.css (Paletten aus catalog.ts)); die Markensperre fürs Marketing liegt in theme.css. Überschreibungen von Komponenten können weiterhin aufgrund der Spezifität gewinnen. Prüfe den gerenderten Radius statt nur die Token-Deklaration.
Überprüfung und Fehlerbehebung
Wenn die Seite auf :3001 liegt, öffnen Sie für die Web-App :3000; :3001 gehört zum separaten Server apps/docs. Fragt ein Test nach Datenbankzugriff, verwenden Sie eine isolierte Entwicklungsdatenbank und prüfen Sie beide .env-Orte. Bleibt derselbe Fehler bestehen, nennen Sie beim Hilfegesuch den Befehl und die bereinigte erste Fehlermeldung. Deaktivieren Sie niemals Zugriffskontrollen und schreiben Sie keine Geheimnisse in Protokolle.
Behebe einen fehlgeschlagenen Prüfschritt nicht, indem du Autorisierung deaktivierst, Geheimnisse protokollierst oder übersprungene Infrastrukturprüfungen als bestanden wertest. Erstelle eine kleine Reproduktion und erfasse die relevanten nicht geheimen Konfigurationswerte. Führe nach der Korrektur die fehlgeschlagene Prüfung und anschließend die betroffenen Regressionstests erneut aus.