Troubleshooting Guide

Use this page to diagnose common high-impact issues quickly.

Local Setup Failures

Symptom: app does not start.

• Verify Node.js and npm versions.
• Run dependency install again and check lockfile consistency.
• Confirm required environment variables are present.

Auth Failures

Symptom: sign-in fails or callback loops.

• Confirm NEXTAUTH_URL matches current host.
• Confirm Google redirect URI is configured correctly.
• Check NEXTAUTH_SECRET is present and stable for the environment.

Database And Migration Failures

Symptom: API errors with database connection or missing table.

• Verify DATABASE_URL credentials and host reachability.
• Check SSL flag compatibility for environment.
• Re-run migration status and confirm latest migration applied.

Auction And Bidding Issues

Symptom: bid rejected unexpectedly.

Possible causes:

• Entered amount is not greater than current amount.
• Auction already ended or is canceled.
• User is banned from the auction.

Action:

• Inspect auction state and user ban records.

Chat Duplication Or Timing Issues

Symptom: repeated messages or delayed appearance.

Cause:

• Polling overlap and client-side merge collisions.

Fix:

• Ensure deduplication by stable message identifier.
• Verify polling interval and cursor handling.

Payment And Callback Issues

Symptom: winner cannot complete payment or status does not update.

• Confirm user is current computed winner.
• Confirm Stripe keys and webhook secret are correct.
• Verify payment completion handler idempotency logic.
• Check webhook delivery logs for signature or network failures.

Admin Access Issues

Symptom: admin route denied.

• Confirm user role in database is admin.
• Confirm middleware and API role checks are consistent.
• Confirm ADMIN_EMAILS bootstrap values are correct for environment.

Missing Environment Variable Diagnostics

Recommended practice:

• Fail fast on startup for required variables.
• Log clear, non-secret diagnostic messages for missing keys.