Troubleshooting

Goal

Quickly diagnose and fix common issues with Coachable Cards.

Quick Start

Most common issues:

Auth not working → Check Supabase env vars
Routing broken → Check middleware configuration
PostHog not firing → Check PostHog env vars
Email not arriving → Check Resend API key

Auth Issues

Symptom: "Authentication required" or login fails

Symptoms:

Can't log in
"Authentication required" errors
Session not persisting
Redirect loops on login

Causes:

Missing Supabase environment variables
Wrong Supabase credentials
CORS issues
Cookie/session issues

Fix:

Check environment variables:

# Verify these are set
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...

Verify Supabase project:
- Go to Supabase Dashboard
- Check project URL matches NEXT_PUBLIC_SUPABASE_URL
- Verify anon key matches NEXT_PUBLIC_SUPABASE_ANON_KEY
Check browser console:
- Open DevTools → Console
- Look for Supabase connection errors
- Check for CORS errors

Clear cookies and retry:

// In browser console
document.cookie.split(";").forEach(c => {
  document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=" + new Date().toUTCString() + ";path=/");
});
location.reload();

Restart dev server:
```
# Stop server (Ctrl+C)
npm run dev
```

Still not working? Check Environment Variables Reference

Middleware Routing Issues

Symptom: Routes not working, 404s, wrong pages loading

Symptoms:

Subdomain routes return 404
Wrong page loads for route
Routes redirect incorrectly
Middleware errors in console

Causes:

Middleware configuration issue
Subdomain not recognized
Route conflict
Next.js routing cache

Fix:

Check middleware logs:

# Look for middleware logs in terminal
# Should see: "Middleware - hostname: X, pathname: Y, subdomain: Z"

Verify subdomain format:

✅ leadership.c.cards
✅ mydeck.c.cards
❌ Leadership.c.cards (case sensitive in some cases)
❌ my-deck!.c.cards (invalid characters)

Check special subdomains:
- Is your subdomain in the special list? (See URL Patterns)
- Special subdomains route differently than deck subdomains
Clear Next.js cache:
```
rm -rf .next
npm run dev
```
Check middleware.ts:
- Verify routing rules are correct
- Check for conflicting routes
- Ensure subdomain extraction works

Common gotchas:

Subdomains are case-insensitive, but paths are case-sensitive
Special subdomains (like app, create) route differently
Trailing slashes can cause issues

Still not working? Check URL Patterns Reference

PostHog Not Firing

Symptom: Analytics events not tracked

Symptoms:

No events in PostHog dashboard
Console errors about PostHog
Analytics not working

Causes:

Missing PostHog environment variables
Wrong PostHog host
Ad blockers blocking PostHog
PostHog not initialized

Fix:

Check environment variables:

NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxx
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

Verify PostHog initialization:

// Check browser console
// Should see: "PostHog initialized" or similar

Check for ad blockers:
- Disable ad blockers
- PostHog might be blocked
- Try incognito mode
Verify PostHog project:
- Go to PostHog Dashboard
- Check project key matches NEXT_PUBLIC_POSTHOG_KEY
- Verify host matches NEXT_PUBLIC_POSTHOG_HOST

Test PostHog manually:

// In browser console
window.posthog?.capture('test-event')
// Check PostHog dashboard for event

Check network tab:
- Open DevTools → Network
- Filter for "posthog"
- Should see requests to PostHog API
- Check for errors (4xx, 5xx)

Still not working? Check PostHog project settings and API keys.

Email Capture Not Arriving

Symptom: Emails not sending or not arriving

Symptoms:

Email form submits but no email
"Email sent" message but nothing arrives
Error when trying to send email
Emails go to spam

Causes:

Missing Resend API key
Wrong Resend configuration
Email domain not verified
Emails in spam folder

Fix:

Check Resend API key:

RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxx
RESEND_FROM_EMAIL=Coachable Cards <noreply@c.cards>
RESEND_REPLY_TO=support@coachablecards.com

Verify Resend account:
- Go to Resend Dashboard
- Check API key is active
- Verify domain is verified (if using custom domain)

Check server logs:

# Look for Resend API errors in terminal
# Should see success/error messages

Test Resend API directly:

curl -X POST https://api.resend.com/emails \
  -H "Authorization: Bearer $RESEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Coachable Cards <noreply@c.cards>",
    "to": "your-email@example.com",
    "subject": "Test",
    "html": "<p>Test email</p>"
  }'

Check spam folder:
- Emails might be in spam
- Check spam/junk folder
- Mark as "Not Spam" if found
Verify email addresses:
- Check "to" email is correct
- Verify email format is valid
- Test with different email address

Still not working? Check Resend dashboard for delivery status and errors.

Checklist

Before reporting an issue, check:

[ ] Environment variables are set correctly
[ ] Dev server restarted after env changes
[ ] Browser console checked for errors
[ ] Network tab checked for failed requests
[ ] Cookies cleared and retried
[ ] Incognito mode tested (rules out extensions)
[ ] Different browser tested
[ ] Server logs checked

Getting Help

If you've tried all fixes and still have issues:

Check the relevant reference:
- Environment Variables
- URL Patterns
Gather information:
- Browser console errors
- Network tab errors
- Server terminal logs
- Environment variable names (not values!)
Report the issue:
- Include symptoms
- Include what you've tried
- Include error messages
- Include environment (local/production)

Next Steps

Environment Variables - Verify your setup
URL Patterns - Understand routing
First Deck Guide - Get started

Still stuck? Check the relevant reference guide or review your environment setup.