❓ 7. Troubleshooting & FAQ

Solutions to common issues encountered during development.

🤖 AI Issues

"Gemini 429 Rate Limit"

Symptoms: AI actions fail or take a long time, logs show 429 Too Many Requests.

Cause: The Google Gemini Free Tier has a request-per-minute limit.

Solution:

1. Wait a minute. The system has built-in backoff and will retry.
2. Add Fallback Keys: Add GROQ_API_KEY or MISTRAL_API_KEY to your .env. The system will auto-switch.

"AI returns empty JSON"

Cause: The model might have hallucinated or formatted the response poorly.

Solution: Check server logs. The src/lib/ai.ts has error handling to catch JSON parse errors. Retry the action.

🗄️ Database Issues

"Prisma Client not initialized"

Cause: You installed a new package or pulled changes but didn't regenerate the client.

Solution: Run npx prisma generate.

"Unique constraint failed"

Cause: You are trying to create a user with an email that already exists.

Solution: Check your database data. Use specific error handling in your server actions to catch P2002 (Prisma unique constraint error).

🔐 Authentication Issues

"Login Loop" / "Session is null"

Symptoms: You log in, get redirected to dashboard, and immediately bounce back to login.

Cause: Cookie security settings. - In src/lib/auth.ts, we set secure: process.env.NODE_ENV === "production". - If you are running locally but NODE_ENV is accidentally set to production, the browser will REJECT the cookie because you aren't on HTTPS.

Solution: Ensure NODE_ENV="development" in your .env file locally.

🐛 Debugging Tips

1. Check Server Logs: Next.js server actions log to the terminal where you ran npm run dev.
2. Prisma Studio: Use npx prisma studio to inspect the actual data state.
3. Browser Network Tab: Inspect the Payload and Response of the Server Action (it looks like a POST request to the current URL).

---

🏠 Return to Home