Dokumentation

Fehlerbehebung

Häufige Motoko-Base-Probleme und Fixes — Auth, OAuth, Datenbank, E-Mail, Billing, Storage, Sentry und Build-Fehler.

Schnelle Fixes für Probleme, die oft beim ersten Setup oder Produktions-Deploy auftreten. Env-Details: Environment Variables.

Authentifizierung funktioniert nicht

Symptome: Kein Sign-in, Session nach Refresh weg, Redirect-Loops, Cookies nicht gesetzt.

Check	Fix
`BETTER_AUTH_SECRET` fehlt	In `.env` setzen — in Produktion erforderlich
`BETTER_AUTH_URL` falsch	Muss zur URL passen, die du im Browser öffnest (inkl. `http://` vs. `https://`, Port, keine Trailing-Slash-Probleme)
Abweichung zu `NEXT_PUBLIC_APP_URL`	Beide in jeder Umgebung auf dieselbe Origin ausrichten
Datenbank down / Migrationen nicht gelaufen	`DATABASE_URL` prüfen, `pnpm db:migrate` ausführen
E-Mail nicht verifiziert	Dashboard erfordert Verifizierung — Posteingang prüfen oder `/verify-email` nutzen

Symptome: redirect_uri_mismatch, Google-/GitHub-Fehler nach Authorize, Social-Buttons deaktiviert.

Check	Fix
Button deaktiviert	Beide `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` setzen (oder GitHub-Paar); Dev-Server neu starten
Callback-URL-Mismatch	Provider-Konsole muss exakt `{BETTER_AUTH_URL}/api/auth/callback/google` oder `.../github` haben
Produktion vs. lokal	Separate Callback-URLs für Localhost und Produktionsdomain hinzufügen
Google-Testmodus	Konto als Testnutzer auf dem OAuth-Consent-Screen hinzufügen

Symptome: App crasht beim Boot, Migrationen scheitern, ECONNREFUSED, Timeout-Fehler.

Check	Fix
`DATABASE_URL` fehlt oder falsch	Aus Supabase-/Host-Dashboard kopieren; nie `NEXT_PUBLIC_*` nutzen
Migrationen nicht angewendet	`pnpm db:migrate`
Pooler vs. direkt	Runtime: Transaction-Pooler (oft Port `6543`). Migrationen: direkte URL (Port `5432`) versuchen, wenn DDL scheitert
Supabase-Projekt pausiert	Projekt im Supabase-Dashboard wiederherstellen
`prepare: false`	Bereits in `src/lib/db/index.ts` gesetzt — für Supabase-Pooler erforderlich; Prepared Statements nicht aktivieren

Symptome: Keine Verifizierungs-E-Mail nach Sign-up, Forgot-Password tut nichts, Welcome-Mail fehlt.

Check	Fix
Resend nicht konfiguriert	`RESEND_API_KEY` und `EMAIL_FROM` setzen
Falscher Absender	In Produktion verifizierte Domain nutzen; zum Testen `onboarding@resend.dev` versuchen
`BETTER_AUTH_URL` falsch	Reset-/Verifizierungslinks zeigen auf falschen Host — Origin korrigieren
Fehler auf Forgot-Password-Seite	Seite prüft `isEmailConfigured()` — beide Resend-Vars erforderlich
Resend-Dashboard	Resend-Logs auf Bounces oder API-Fehler prüfen

Symptome: Billing-Seite zeigt „not configured“, Checkout-Button scheitert, bleibt nach Zahlung auf Free.

Check	Fix
Fehlende Env-Vars	`POLAR_ACCESS_TOKEN`, `POLAR_PRO_MONTHLY_PRODUCT_ID`, `POLAR_WEBHOOK_SECRET`
Sandbox vs. Production	`POLAR_SERVER=sandbox` mit Sandbox-Token/Produkt — oder `production` mit Live-Credentials
Webhook-URL	`{APP_URL}/api/billing/webhooks/polar` — muss von Polar erreichbar sein
Nach Checkout	Billing-Seite nutzt `getFreshBillingSummary` beim Success-Redirect; Webhook-Zustellung bestätigen
Kein Polar-Customer	Nutzer braucht einen Polar-Customer (bei Sign-up erstellt, wenn Billing konfiguriert ist) vor dem Portal

Symptome: Storage-Seite zeigt Config-Meldung, Presigned-URL-Fehler, Browser-Upload-CORS-Fehler, 403 bei PUT.

Check	Fix
Fehlende `R2_*`-Vars	Account-ID, Access Key, Secret, Bucket-Name setzen
Bucket-Name mit Slash	`my-bucket/demo` → Bucket `my-bucket`, Prefix `demo/` — oder `R2_PREFIX` nutzen
CORS	App-Origin zur R2-Bucket-CORS-Policy in Cloudflare hinzufügen
Datei zu groß / falsches MIME	Limits in `src/features/storage/config.ts`
HEAD-Validierung scheitert	Server validiert Upload nach PUT — Objekt im R2-Dashboard prüfen

Symptome: Keine Issues im Sentry-Dashboard nach Testfehler.

Check	Fix
Test in `next dev`	Sentry ist während Dev deaktiviert — `pnpm build && pnpm start` nutzen oder auf deployed Production testen
DSN fehlt	`NEXT_PUBLIC_SENTRY_DSN` setzen
Falsches Projekt	Bestätigen, dass DSN zum betrachteten Sentry-Projekt passt
Ad-Blocker	Browser kann Sentry blockieren — `/sentry-tunnel`-Route oder Server-Fehler testen
Source Maps	`SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT` zur Build-Zeit setzen für lesbare Stacks

Symptome: pnpm build endet lokal oder in CI mit Fehlern.

Check	Fix
Node-Version	Erfordert Node ≥ 22 — `node -v` ausführen
Typfehler	`pnpm typecheck` — gemeldete TypeScript-Probleme beheben
Lint-Fehler	`pnpm lint`
Fehlende Env beim Build	Die meisten Vars sind nur Runtime; Sentry-Upload-Vars nur bei Source Maps nötig
MDX / Docs	`pnpm install` ausführen, damit `postinstall` (`fumadocs-mdx`) abgeschlossen wird
Lockfile	`pnpm install` nutzen — npm/yarn nicht mischen

pnpm lint && pnpm typecheck && pnpm test && pnpm build

Installation und Produktions-Setup erneut lesen
Deine .env mit .env.example vergleichen
Integrations-Dashboards prüfen (Resend, Polar, Cloudflare, PostHog, Sentry)
Im Repo-README und Feature-READMEs unter src/lib/email/, src/lib/security/ usw. suchen

Scripts — Befehlsreferenz.

Konfigurationsreferenz — Index der Config-Dateien.