Zum Hauptinhalt springen

Troubleshooting

Häufige Probleme und Lösungen bei der Entwicklung mit Roestify.

Build & Development​

npm run dev startet nicht​

Symptom: Server startet, aber Seiten laden nicht.

Lösung:

  1. Prüfe ob .env.local existiert und DATABASE_URL korrekt ist
  2. Prüfe ob die DB erreichbar ist: npx tsx scripts/migrate.ts
  3. Lösche den Cache: rm -rf .next && npm run dev

TypeScript-Fehler nach Paket-Update​

Lösung:

rm -rf node_modules .next
npm install
npm run dev

Turbopack-Fehler​

Symptom: HMR funktioniert nicht, Seiten aktualisieren sich nicht.

Lösung: Dev-Server neustarten. Turbopack hat gelegentlich Cache-Probleme.

Datenbank​

Migration schlägt fehl​

Symptom: npm run db:migrate gibt SQL-Fehler.

Ursache: Migration ist nicht idempotent.

Lösung: Jede Migration muss idempotent sein:

  • CREATE TABLE → CREATE TABLE IF NOT EXISTS
  • CREATE TYPE → DO $$ BEGIN CREATE TYPE ... ; EXCEPTION WHEN duplicate_object THEN NULL; END $$;
  • ALTER TABLE ... ADD COLUMN → ALTER TABLE ... ADD COLUMN IF NOT EXISTS
  • CREATE INDEX → CREATE INDEX IF NOT EXISTS

Siehe auch: Migrationen

RLS-Verletzung (403)​

Symptom: API gibt 403 zurück, obwohl der User eingeloggt ist.

Ursache: Die Query versucht auf Daten eines anderen Tenants zuzugreifen, oder der RLS-Context ist nicht gesetzt.

Debugging:

  1. Prüfe ob tenantId im tRPC-Context gesetzt ist
  2. Prüfe die RLS-Policy auf der betroffenen Tabelle
  3. Teste die Query direkt mit SQL und explizitem tenant_id

Parallele Migrationen​

Symptom: Zwei Instanzen versuchen gleichzeitig Migrationen auszuführen.

Lösung: Der Migration-Runner verwendet pg_try_advisory_lock(73719283). Nur eine Instanz kann gleichzeitig migrieren.

Auth​

Session abgelaufen / Redirect-Loop​

Symptom: Nach Login sofort wieder auf Login-Seite.

Debugging:

  1. Prüfe AUTH_SECRET in .env.local
  2. Prüfe ob die DB erreichbar ist (Sessions werden dort gespeichert)
  3. Cookies löschen und neu einloggen

Google OAuth funktioniert nicht lokal​

Lösung: NEXTAUTH_URL=http://localhost:3000 muss in .env.local gesetzt sein. Google OAuth Redirect-URI muss http://localhost:3000/api/auth/callback/google enthalten.

tRPC​

FORBIDDEN mit cause.code = "MODULE_INACTIVE"​

Symptom: tRPC-Query gibt 403 zurück mit Modul-Fehler.

Ursache: Das Feature-Modul ist für diesen Tenant nicht aktiviert.

Lösung: Prüfe tenant_modules Tabelle. Module werden beim Onboarding basierend auf dem Plan geseeded.

Hydration-Mismatch​

Symptom: React-Warnung "A tree hydrated but some attributes of the server rendered HTML didn't match."

Ursache: Server und Client rendern unterschiedlichen Output (z.B. durch typeof window, new Date() ohne Timezone).

Lösung:

  • Kein typeof window oder typeof navigator im Render-Body
  • Stattdessen: useState(fallback) + useEffect(() => setX(browserValue), [])
  • Datumsformatierung immer mit timeZone: "Europe/Berlin"

Shopify / DHL​

Shopify-Webhook kommt nicht an​

Debugging:

  1. Prüfe Webhook-Konfiguration in Shopify Admin
  2. Prüfe ob die App öffentlich erreichbar ist (kein localhost)
  3. Prüfe Signatur-Validierung in den Server-Logs

DHL-Label-Erstellung schlägt fehl​

Häufige Ursachen:

  • Credentials nicht konfiguriert oder abgelaufen
  • Adresse nicht DHL-konform (Hausnummer fehlt, PLZ ungültig)
  • Rate Limit erreicht