Documentation

Dépannage

Problèmes courants de Motoko Base et correctifs — auth, OAuth, base de données, e-mail, billing, storage, Sentry et échecs de build.

Ouvrir dansChatGPT Claude Cursor

Correctifs rapides pour les problèmes qui apparaissent souvent lors du premier setup ou du déploiement en production. Pour les détails d’env, voir Environment Variables.

L’authentification ne fonctionne pas

Symptômes : Impossible de se connecter, session perdue au refresh, boucles de redirection, cookies non définis.

Vérification	Correctif
`BETTER_AUTH_SECRET` manquant	Définir dans `.env` — requis en production
`BETTER_AUTH_URL` incorrect	Doit correspondre à l’URL ouverte dans le navigateur (y compris `http://` vs `https://`, port, pas de problème de slash final)
Décalage avec `NEXT_PUBLIC_APP_URL`	Aligner les deux sur la même origine dans chaque environnement
Base de données down / migrations non exécutées	Vérifier `DATABASE_URL`, lancer `pnpm db:migrate`
E-mail non vérifié	Le dashboard exige la vérification — vérifier la boîte mail ou utiliser `/verify-email`

Voir Better Auth et Installation.

Erreur de callback OAuth

Symptômes : redirect_uri_mismatch, erreur Google/GitHub après autorisation, boutons sociaux désactivés.

Vérification	Correctif
Bouton désactivé	Définir les deux `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` (ou la paire GitHub) ; redémarrer le serveur de dev
URL de callback incorrecte	La console du fournisseur doit avoir exactement `{BETTER_AUTH_URL}/api/auth/callback/google` ou `.../github`
Production vs local	Ajouter des URLs de callback séparées pour localhost et le domaine de production
Mode test Google	Ajouter votre compte comme utilisateur de test sur l’écran de consentement OAuth

Voir OAuth Setup.

Échec de connexion à la base de données

Symptômes : L’app plante au démarrage, migrations échouent, ECONNREFUSED, erreurs de timeout.

Vérification	Correctif
`DATABASE_URL` absent ou incorrect	Copier depuis le dashboard Supabase/hôte ; ne jamais utiliser `NEXT_PUBLIC_*`
Migrations non appliquées	`pnpm db:migrate`
Pooler vs direct	Runtime : transaction pooler (souvent port `6543`). Migrations : essayer l’URL directe (port `5432`) si le DDL échoue
Projet Supabase en pause	Restaurer le projet dans le dashboard Supabase
`prepare: false`	Déjà défini dans `src/lib/db/index.ts` — requis pour le pooler Supabase ; ne pas activer les prepared statements

Voir Database et Migrations.

Les e-mails ne sont pas envoyés

Symptômes : Pas d’e-mail de vérification après inscription, forgot-password ne fait rien, e-mail de bienvenue manquant.

Vérification	Correctif
Resend non configuré	Définir `RESEND_API_KEY` et `EMAIL_FROM`
Expéditeur incorrect	Utiliser un domaine vérifié en production ; pour les tests essayer `onboarding@resend.dev`
`BETTER_AUTH_URL` incorrect	Les liens de reset/vérification pointent vers le mauvais hôte — corriger l’origine
Erreur page forgot-password	La page vérifie `isEmailConfigured()` — les deux vars Resend sont requises
Dashboard Resend	Vérifier les logs Resend pour les bounces ou erreurs API

Voir Email (Resend).

Le checkout Polar ne s’ouvre pas

Symptômes : La page billing affiche « not configured », le bouton checkout échoue, reste sur Free après paiement.

Vérification	Correctif
Variables d’environnement manquantes	`POLAR_ACCESS_TOKEN`, `POLAR_PRO_MONTHLY_PRODUCT_ID`, `POLAR_WEBHOOK_SECRET`
Sandbox vs production	`POLAR_SERVER=sandbox` avec token/produit sandbox — ou `production` avec identifiants live
URL du webhook	`{APP_URL}/api/billing/webhooks/polar` — doit être joignable depuis Polar
Après le checkout	La page billing utilise `getFreshBillingSummary` sur le redirect de succès ; confirmer la livraison du webhook
Pas de client Polar	L’utilisateur a besoin d’un client Polar (créé à l’inscription quand le billing est configuré) avant le portail

Voir Payments (Polar).

Échec d’upload R2

Symptômes : La page storage affiche un message de config, erreur d’URL présignée, échec CORS d’upload navigateur, 403 sur PUT.

Vérification	Correctif
Vars `R2_*` manquantes	Définir account ID, access key, secret, nom du bucket
Nom de bucket avec slash	`my-bucket/demo` → bucket `my-bucket`, prefix `demo/` — ou utiliser `R2_PREFIX`
CORS	Ajouter l’origine de l’app à la politique CORS du bucket R2 dans Cloudflare
Fichier trop volumineux / mauvais MIME	Limites dans `src/features/storage/config.ts`
Échec de validation HEAD	Le serveur valide l’upload après PUT — vérifier que l’objet existe dans le dashboard R2

Voir Storage (R2).

Sentry ne reçoit pas les erreurs

Symptômes : Aucune issue dans le dashboard Sentry après un erreur de test.

Vérification	Correctif
Test dans `next dev`	Sentry est désactivé en dev — utiliser `pnpm build && pnpm start` ou tester en production déployée
DSN absent	Définir `NEXT_PUBLIC_SENTRY_DSN`
Mauvais projet	Confirmer que le DSN correspond au projet Sentry consulté
Bloqueurs de pubs	Le navigateur peut bloquer Sentry — essayer la route `/sentry-tunnel` ou une erreur côté serveur
Source maps	Définir `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT` au build pour des stacks lisibles

Voir Monitoring (Sentry).

Échec du build

Symptômes : pnpm build se termine avec des erreurs en local ou en CI.

Vérification	Correctif
Version de Node	Nécessite Node ≥ 22 — lancer `node -v`
Erreurs de type	`pnpm typecheck` — corriger les problèmes TypeScript signalés
Erreurs de lint	`pnpm lint`
Env manquant au build	La plupart des vars sont runtime uniquement ; vars d’upload Sentry seulement si source maps
MDX / docs	Lancer `pnpm install` pour que `postinstall` (`fumadocs-mdx`) se termine
Lockfile	Utiliser `pnpm install` — ne pas mélanger npm/yarn

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

Toujours bloqué ?

Relire Installation et Configuration de production
Comparer votre .env à .env.example
Vérifier les dashboards d’intégration (Resend, Polar, Cloudflare, PostHog, Sentry)
Chercher dans le README du dépôt et les README de features sous src/lib/email/, src/lib/security/, etc.

Scripts — Référence des commandes.

Référence de configuration — Index des fichiers de configuration.