Troubleshooting Guide

Step-by-step solutions for common SvelteBolt issues.

Quick Diagnostic Steps

Before diving into specific issues, try these general steps:

1. Check environment variables - Verify all required variables are set
2. Restart development server - Stop and restart bun run dev
3. Clear browser cache - Hard refresh or incognito mode
4. Check browser console - Look for JavaScript errors (F12)
5. Review recent changes - What was the last thing you modified?

Database Issues

❌ "Failed to connect to database"

Symptoms:

• App won't load
• Auth doesn't work
• API requests fail

Solutions:

1. Check Supabase credentials:

# Verify these are set correctly in .env
PUBLIC_SUPABASE_URL=https://your-project.supabase.co
PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
SUPABASE_SERVICE_ROLE_SECRET=eyJhbGciOiJIUzI1NiIs...

2. Verify project status:

   • Go to supabase.com
   • Check if your project is paused (free tier limitation)
   • Ensure project URL matches your environment variable

3. Test connection:

# Test if Supabase is reachable
curl https://your-project.supabase.co/rest/v1/

❌ "Row Level Security policy violation"

Symptoms:

• Can't read/write data
• "Policy violation" errors
• Empty data responses

Solutions:

1. Check RLS policies:

   • Go to Supabase Dashboard → Authentication → Policies
   • Ensure policies exist for your tables
   • Verify policies match your user auth flow

2. Common policy patterns:

-- Allow users to read their own data
CREATE POLICY "Users can read own data" ON profiles
FOR SELECT USING (auth.uid() = user_id);

-- Allow authenticated users to read public data
CREATE POLICY "Authenticated users can read" ON public_data
FOR SELECT TO authenticated;

Authentication Issues

❌ "Sign up/Login not working"

Symptoms:

• Buttons don't respond
• Redirect loops
• "Invalid credentials" errors

Solutions:

1. Check auth configuration:

   • Supabase Dashboard → Authentication → Settings
   • Verify Site URL: http://localhost:5173 (dev) or your domain
   • Add redirect URLs: http://localhost:5173/auth/callback

2. Check email settings:

   • Authentication → Settings → SMTP
   • Verify email templates are enabled
   • Test with a valid email address

3. Verify auth routes:

# Check these files exist:
src/routes/auth/callback/+server.ts
src/routes/auth/confirm/+server.ts

❌ "Session not persisting"

Symptoms:

• User gets logged out on refresh
• Auth state resets
• Inconsistent login state

Solutions:

1. Check session configuration:

// In your Supabase client setup
const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: true,
  },
});

2. Verify cookies/localStorage:
   • Check if auth cookies are being set
   • Ensure localStorage isn't being cleared
   • Check for conflicting auth state

Payment Issues

❌ "Stripe checkout not working"

Symptoms:

• Checkout button doesn't work
• Stripe errors in console
• Payment flow breaks

Solutions:

1. Verify Stripe keys:

# Check these are correct in .env
PUBLIC_STRIPE_KEY=pk_test_51...  # Must start with pk_
STRIPE_SECRET_KEY=sk_test_51...  # Must start with sk_

2. Check test mode:

   • Ensure using test keys in development
   • Use test card numbers: 4242424242424242
   • Verify test mode toggle in Stripe Dashboard

3. Verify webhook setup:

# Check webhook endpoint exists
curl -X POST http://localhost:5173/api/stripe/webhook

❌ "Webhook events not received"

Symptoms:

• Payments succeed but subscriptions not created
• User doesn't get access after payment
• Webhook logs show failures

Solutions:

1. Check webhook URL:

   • Stripe Dashboard → Developers → Webhooks
   • URL should be: https://your-domain.com/api/stripe/webhook
   • For local testing: Use Stripe CLI or ngrok

2. Verify webhook secret:

# Must match the webhook endpoint secret
STRIPE_WEBHOOK_SECRET=whsec_...

3. Test webhook locally:

# Install Stripe CLI
stripe login
stripe listen --forward-to localhost:5173/api/stripe/webhook

Deployment Issues

❌ "Build fails"

Symptoms:

• Deployment fails
• Build errors in logs
• Missing dependencies

Solutions:

1. Check build locally:

bun run build

2. Common build issues:

# Node.js version mismatch
# Solution: Ensure using Node 18+ locally and in deployment

# Missing environment variables
# Solution: Add all required env vars to hosting platform

# Import errors
# Solution: Check all imports are correct

3. Platform-specific fixes:

Vercel:

# Check vercel.json or use auto-detection
# Ensure using @sveltejs/adapter-auto

Netlify:

# Add netlify.toml if needed
[build]
  command = "bun run build"
  functions = "build/server"

❌ "Environment variables not working in production"

Symptoms:

• App works locally but not in production
• Missing API keys errors
• Undefined environment variables

Solutions:

1. Verify all variables are set:

   • Check hosting platform dashboard
   • Ensure exact variable names (case-sensitive)
   • No extra spaces or quotes

2. PUBLIC_ prefix for client-side:

# Client-side variables need PUBLIC_ prefix
PUBLIC_SUPABASE_URL=...
PUBLIC_STRIPE_PUBLIC_KEY=...

# Server-side variables don't need prefix
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...

3. Redeploy after adding variables:
   • Most platforms require redeploy
   • Clear build cache if available

Performance Issues

❌ "Slow page loads"

Solutions:

1. Check database queries:

   • Use Supabase query profiler
   • Add indexes for frequent queries
   • Limit result sets with pagination

2. Optimize images:

// Use proper image optimization
import { enhance } from "$app/forms";

3. Bundle analysis:

# Check bundle size
bun run build
bun run preview

Getting More Help

If these solutions don't work:

1. Check specific error messages - Search for exact error text
2. Review recent changes - What broke it?
3. Test in incognito mode - Rule out cache issues
4. Check GitHub Issues - Someone might have reported it
5. Create a minimal reproduction - Isolate the problem

Still stuck? Visit our Support page for more help options.