Troubleshooting

Solutions to the most common setup and deployment issues in BloggFast.

Last updated:

Tip

Most issues are caused by missing or incorrect environment variables. Start by double-checking your .env.local against the Environment Variables Reference.

Database issues

PrismaClientInitializationError: Can't reach database

Cause: DATABASE_URL is missing, wrong, or using the pooled connection URL instead of the direct connection.

Fix:

  1. Verify DATABASE_URL is set in .env.local
  2. Use the direct (non-pooled) Neon connection string for Prisma
  3. Ensure the URL includes ?sslmode=require
  4. Restart the dev server after changing env vars

Migrations failing with SSL connection error

bash
# Add sslmode to your connection string
DATABASE_URL="postgresql://user:pass@host/db?sslmode=require"

Prisma schema out of sync

bash
npx prisma db push
# or
npx prisma migrate dev --name sync

Authentication issues

Redirect loop on /sign-in

Cause: Neon Auth environment variables are missing or the callback URL isn't registered.

Fix:

  1. Verify all three Neon Auth variables are set in .env.local
  2. In Neon Auth settings, add http://localhost:3000 as an allowed redirect URL

Sessions not persisting after restart

Clear your browser cookies for localhost:3000 and sign in again. If the issue persists, check that your Neon Auth project ID matches the one in your env file.

Sanity CMS issues

Studio shows blank page or CORS error

Cause: The origin http://localhost:3000 isn't allowed in Sanity's CORS settings.

Fix: Go to sanity.io/manage → your project → API → CORS origins. Add http://localhost:3000 with credentials allowed.

Content not showing on the blog

  • Make sure the post is Published in Studio (not just saved as draft)
  • Verify NEXT_PUBLIC_SANITY_PROJECT_ID and NEXT_PUBLIC_SANITY_DATASET are correct
  • Try a hard refresh or clear Next.js cache: rm -rf .next then npm run dev

AI provider issues

AI generation returns a 401 error

Cause: Invalid or missing API key for the active provider.

Fix: Double-check the API key in your .env.local. Ensure there are no extra spaces. Verify the key is active in the provider's dashboard.

AI generation returns a 429 (rate limit) error

You've exceeded the API rate limit. Options:

  • Wait a few minutes and try again
  • Upgrade your API plan with the provider
  • Switch to a faster or cheaper model in the admin AI settings (e.g., gpt-5-nano or gpt-4o-mini)

Email issues

Subscription confirmation email not arriving

  • Check your spam folder
  • Verify RESEND_API_KEY is correct
  • Ensure RESEND_FROM_EMAIL is a domain you've verified in Resend
  • Check the Resend dashboard → Logs for error details

Resend returns a 422 error

The from address domain isn't verified. Either verify your domain in Resend, or use the Resend sandbox email (onboarding@resend.dev) for development testing.

Build and deployment issues

Build fails with Type error

Run npm run build locally first to catch TypeScript errors before pushing to Vercel. Fix any type errors in the output.

bash
npm run build
# Check for output errors

Vercel build succeeds but app crashes on load

Check Vercel's Function Logs for runtime errors. Most common cause: missing environment variables in the Vercel project settings.

Module not found on Vercel but works locally

This is usually a case sensitivity issue — macOS file systems are case-insensitive but Linux (Vercel) is case-sensitive. Check your import paths match the exact file name casing.