Troubleshooting

Webhooks Not Firing

Symptoms: Payments succeed but credits aren't granted.

1. Check Stripe Dashboard → Webhooks for delivery logs
2. Verify STRIPE_WEBHOOK_SECRET matches your Stripe settings
3. Ensure webhook endpoint is publicly accessible
4. Check server logs for signature verification errors

Annual Credits Not Auto-Granting

Symptoms: Users on yearly plans don't receive monthly credits.

1. Verify cron job is running (check /api/cron/subscription-grants)
2. Check subscriptionCreditSchedule / subscription_credit_schedule for nextGrantAt / next_grant_at timestamps
3. Ensure CRON_SECRET is configured correctly

Expiring Credits Not Updating

Symptoms: Daily login credits remain available after their expiry time.

1. Verify cron job is running for /api/cron/credit-expiry
2. Check creditBalanceBucket / credit_balance_bucket rows with expired expiresAt / expires_at values and positive remainingAmount / remaining_amount
3. Ensure CRON_SECRET or cron basic auth credentials are configured correctly

AI Tool Generation Fails

1. Verify VOLCENGINE_API_KEY, VOLCENGINE_BASE_URL, and VOLCENGINE_MODEL
2. Confirm the server runtime can reach the Volcengine endpoint
3. Check aiGeneration / ai_generation rows for failed generation records and error messages
4. Confirm the user has enough credits before generation

User Can't Access Admin Panel

1. Confirm user.role = 'admin' in the database
2. Check requireAdmin() in modules/auth/admin.ts
3. Ensure the user's session is valid (try logging out and back in)

Email Not Sending

1. Verify RESEND_API_KEY and RESEND_FROM_EMAIL
2. If using onboarding@resend.dev, send only to the email registered on your Resend account
3. For production, confirm the sending domain is verified in Resend
4. Check Resend email logs for delivery failures

Database Connection Issues

1. Verify DATABASE_URL connection string
2. Ensure ?sslmode=require for cloud databases
3. Check if your IP is allowlisted (if using IP restrictions)
4. Try connecting directly: psql $DATABASE_URL

Build Errors After Upgrade

If you encounter TypeScript errors after upgrading dependencies:

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
pnpm install

# Try building again
pnpm build