Troubleshooting Common Issues

Quick reference for solving common development problems

Quick Fixes

Most issues can be solved by: clean rebuild (rm -rf dist), hard refresh browser, or waiting 2-3 minutes for propagation.

Deployment Issues

Old Code Still Showing After Deploy

Symptoms:

Deployed new code but seeing old version
Demo data still present after removing it
Code changes not reflected on site

Root Cause: Vite caches build artifacts in dist/ folder.

Solution:

bash

# ❌ WRONG - Deploys cached code
npm run build && npx wrangler pages deploy dist

# ✅ CORRECT - Clean build first
rm -rf dist && npm run build && npx wrangler pages deploy dist

Prevention: Always clean before deploying:

json

// package.json
{
  "scripts": {
    "deploy": "rm -rf dist && npm run build && npx wrangler pages deploy dist --project-name=PROJECT"
  }
}

Custom Domain Not Working

Symptoms:

Preview URL works fine
Custom domain shows old version or doesn't load
Getting 404 or blank page

Root Cause: Custom domain propagation takes 1-2 minutes.

Solution:

Wait 2-3 minutes after deployment
Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
Test in incognito window to avoid cache
Verify preview URL works first

Debugging:

bash

# Check if deployment succeeded
npx wrangler pages deployment list --project-name=PROJECT

# If preview URL works, it's just propagation delay

Wrong Project Deployed

Symptoms:

Customer site showing admin features
Admin site showing customer UI
Demo data on production site

Root Cause: Deployed to wrong Cloudflare project.

Solution: Verify project name in deployment command:

bash

# For customer portal
npx wrangler pages deploy dist --project-name=muse-customer

# For admin portal
npx wrangler pages deploy dist --project-name=muse-admin

Prevention: Use package.json scripts with hardcoded project names.

Environment Variable Issues

Environment Variables Not Updating

Symptoms:

Changed .env file but app still uses old values
API keys updated but not working
Configuration changes not reflected

Root Cause: Vite bakes environment variables at build time, not runtime.

Solution:

Update .env.production file
Clean rebuild:
bash
```
rm -rf dist && npm run build
```
Redeploy:
bash
```
npx wrangler pages deploy dist
```

Important: Just redeploying without rebuilding won't work!

Secrets Not Working in Cloudflare

Symptoms:

Backend API returns errors about missing secrets
Stripe integration fails
Database connection fails

Root Cause: Cloudflare binds secrets at deployment time.

Solution:

Set the secret:

bash

npx wrangler pages secret put SECRET_NAME --project-name=PROJECT

Redeploy the application:
bash
```
npm run deploy
```

Verify secrets are set:

bash

npx wrangler pages secret list --project-name=PROJECT

Database Issues

Database Migration Didn't Apply

Symptoms:

Query fails with "table doesn't exist"
Column not found errors
Migration seemed to succeed but changes not there

Root Cause: Forgot --remote flag (migration only ran locally).

Solution:

bash

# Run migration on production database
npx wrangler d1 execute YOUR-DB-NAME --file=migration.sql --remote

# Verify it worked
npx wrangler d1 execute YOUR-DB-NAME --command="SELECT * FROM new_table LIMIT 1" --remote

Always Use --remote for Production

Without --remote, migrations only affect your local database!

Database Query Fails in Production

Symptoms:

Works locally but fails in production
Column doesn't exist error
Wrong data type errors

Root Cause: Local and remote databases out of sync.

Solution:

Check remote schema:

bash

npx wrangler d1 execute DB-NAME --command="PRAGMA table_info(table_name)" --remote

Compare with local schema
Run missing migrations with --remote

CORS Errors

Cross-Origin Request Blocked

Symptoms:

Admin app can't call customer API
"CORS policy" error in console
Fetch fails with network error

Root Cause: Origin not in CORS allowlist.

Solution: Add origin to API endpoint:

typescript

const allowedOrigins = [
  'https://ncmuse.co',
  'https://staff.ncmuse.co',
  'https://localhost:5173', // Dev
  'https://PREVIEW-URL.pages.dev', // Add preview URLs
];

// In API response
headers: {
  'Access-Control-Allow-Origin': origin,
  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type',
}

Quick fix for development:

Add your localhost and preview URLs to allowlist
Rebuild and redeploy

Form Data Issues

Form Submission Loses Data

Symptoms:

Form submits but backend doesn't receive all fields
Some fields are undefined
Data transformation errors

Root Cause: Frontend field names don't match backend expectations.

Solution:

Log the data at both ends:

typescript

// Frontend
console.log('Sending:', formData);

// Backend
console.log('Received:', await request.json());

Check field name mismatches:
- Frontend: customerName
- Backend expects: customer_name
Fix naming to match
Test end-to-end immediately

Prevention: Use TypeScript interfaces shared between frontend and backend.

Build Errors

"Module not found" During Build

Symptoms:

Build fails with import errors
Module not found errors
Cannot resolve errors

Solution:

bash

# 1. Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# 2. Clear Next.js cache (if using Next.js)
rm -rf .next

# 3. Clear Vite cache
rm -rf dist

# 4. Try build again
npm run build

Build Succeeds But App Crashes

Symptoms:

Build completes without errors
Deployment succeeds
App loads but crashes immediately

Root Cause: Runtime error not caught during build.

Solution:

Check Cloudflare Workers logs:

bash

npx wrangler pages deployment tail --project-name=PROJECT

Look for console.error messages
Check for:
- Missing environment variables
- Database connection issues
- API endpoint typos

Authentication Issues

Symptoms:

Can log in on preview URL
Login fails on custom domain
"Session expired" immediately

Root Cause: Cookie domain mismatch or propagation delay.

Solution:

Wait 2-3 minutes for custom domain propagation
Clear cookies for custom domain
Hard refresh browser
Try incognito mode

OAuth Account Linking Fails

Symptoms:

User can't sign in with Google/Facebook
"Account already exists" error
Email conflict errors

Root Cause: OAuth provider requires allowDangerousEmailAccountLinking: true.

Solution:

typescript

// In OAuth provider config
GoogleProvider({
  clientId: process.env.GOOGLE_ID,
  clientSecret: process.env.GOOGLE_SECRET,
  allowDangerousEmailAccountLinking: true,
}),

Important: Also create accounts manually in signIn callback.

Stripe Integration Issues

Webhook Not Firing

Symptoms:

Checkout completes but order not created
Payment succeeds but no confirmation email
Webhook endpoint returning errors

Solution:

Verify webhook secret:

bash

npx wrangler pages secret list --project-name=PROJECT
# Should show STRIPE_WEBHOOK_SECRET

Check Stripe dashboard:
- Go to Developers > Webhooks
- Click on endpoint
- Check recent deliveries for errors
Verify endpoint URL is correct:
- Test mode: Use test webhook secret
- Live mode: Use live webhook secret

Test signature verification:

bash

# Use Stripe CLI
stripe listen --forward-to https://YOUR-DOMAIN/api/webhooks/stripe-membership
stripe trigger checkout.session.completed

Stripe Test Mode vs Live Mode

Symptoms:

Payments fail in production
"No such customer" errors
Key mismatch errors

Root Cause: Using test keys in production or vice versa.

Solution: Verify mode consistency:

bash

# Check current mode
echo $VITE_STRIPE_PUBLISHABLE_KEY | grep "pk_test" && echo "TEST MODE" || echo "LIVE MODE"

# Frontend and backend must match:
# TEST: pk_test_... + sk_test_... + whsec_test...
# LIVE: pk_live_... + sk_live_... + whsec_live...

Performance Issues

Slow Page Loads

Symptoms:

Pages take several seconds to load
API requests timeout
Slow initial render

Solution:

Check bundle size:

bash

npm run build
# Look for large chunk warnings

Implement code splitting:

typescript

const HeavyComponent = lazy(() => import('./HeavyComponent'));

Optimize images:
- Use Cloudflare R2 with CDN
- Compress images before upload
- Use appropriate sizes
Check database queries:
- Add indexes on frequently queried columns
- Avoid SELECT *
- Use LIMIT for large result sets

Cache Issues

Browser Showing Stale Content

Symptoms:

Changes deployed but not visible
Old images/styles showing
JavaScript not updating

Solution:

Hard refresh:
- Mac: Cmd + Shift + R
- Windows/Linux: Ctrl + Shift + R
Clear browser cache:
- Chrome: DevTools > Network > Disable cache
Test in incognito mode

Verify deployment succeeded:

bash

npx wrangler pages deployment list --project-name=PROJECT
# Check timestamp of latest deployment

Symptoms:

Admin updates menu but customers see old data
New items don't appear
Price changes not reflected

Root Cause: Cache version not incremented.

Solution:

Check version field in database:

bash

npx wrangler d1 execute DB --command="SELECT version FROM menu_version" --remote

Increment version when updating menu:

sql

UPDATE menu_version SET version = version + 1;

Frontend checks version on each load:
typescript
```
const cacheKey = `menu:full:v${version}`;
```

Debugging Tips

Enable Detailed Logging

Frontend:

typescript

// In development
if (import.meta.env.DEV) {
  console.log('API Request:', data);
}

Backend:

typescript

// In Cloudflare Worker
export default {
  async fetch(request, env) {
    console.log('Request:', {
      url: request.url,
      method: request.method,
    });
    // ... handle request
  }
}

Monitor Real-Time Logs

bash

# Watch Cloudflare Workers logs
npx wrangler pages deployment tail --project-name=PROJECT

# Filter for errors only
npx wrangler pages deployment tail --project-name=PROJECT --format=pretty | grep ERROR

Test API Endpoints Directly

bash

# Use curl to test endpoints
curl -X POST https://ncmuse.co/api/endpoint \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# With authentication
curl https://staff.ncmuse.co/api/admin/orders \
  -H "Cookie: session=YOUR_SESSION_COOKIE"

Getting Help

If you're stuck after trying these solutions:

Check Cloudflare Dashboard:
- Analytics > Errors
- Workers > Logs
- Pages > Deployments
Review Related Documentation:
Ask for Help:
- Provide error messages
- Share what you've already tried
- Include relevant code snippets
- Specify which app (customer/admin)

Still having issues? Consult with a senior developer or check the full documentation.

Troubleshooting Common Issues ​

Deployment Issues ​

Old Code Still Showing After Deploy ​

Custom Domain Not Working ​

Wrong Project Deployed ​

Environment Variable Issues ​

Environment Variables Not Updating ​

Secrets Not Working in Cloudflare ​

Database Issues ​

Database Migration Didn't Apply ​

Database Query Fails in Production ​

CORS Errors ​

Cross-Origin Request Blocked ​

Form Data Issues ​

Form Submission Loses Data ​

Build Errors ​

"Module not found" During Build ​

Build Succeeds But App Crashes ​

Authentication Issues ​

Login Works on Preview But Not Custom Domain ​

OAuth Account Linking Fails ​

Stripe Integration Issues ​

Webhook Not Firing ​

Stripe Test Mode vs Live Mode ​

Performance Issues ​

Slow Page Loads ​

Cache Issues ​

Browser Showing Stale Content ​

Menu Data Not Updating ​

Debugging Tips ​

Enable Detailed Logging ​

Monitor Real-Time Logs ​

Test API Endpoints Directly ​

Getting Help ​

Troubleshooting Common Issues

Deployment Issues

Old Code Still Showing After Deploy

Custom Domain Not Working

Wrong Project Deployed

Environment Variable Issues

Environment Variables Not Updating

Secrets Not Working in Cloudflare

Database Issues

Database Migration Didn't Apply

Database Query Fails in Production

CORS Errors

Cross-Origin Request Blocked

Form Data Issues

Form Submission Loses Data

Build Errors

"Module not found" During Build

Build Succeeds But App Crashes

Authentication Issues

Login Works on Preview But Not Custom Domain

OAuth Account Linking Fails

Stripe Integration Issues

Webhook Not Firing

Stripe Test Mode vs Live Mode

Performance Issues

Slow Page Loads

Cache Issues

Browser Showing Stale Content

Menu Data Not Updating

Debugging Tips

Enable Detailed Logging

Monitor Real-Time Logs

Test API Endpoints Directly

Getting Help