Appendix C: LinkHub Troubleshooting

Common issues and solutions encountered during LinkHub development.

Dev Environment Issues

Symptom	Cause	Solution
"command not found: node"	Node.js not installed	Install Node.js and retry
"command not found: claude"	Claude Code not installed	`npm install -g @anthropic-ai/claude-code`
npm install fails	Network or permission issue	`sudo npm install` or check network
localhost:3000 not opening	Another process using port	Close other terminals or change port

Database/Auth Issues

Symptom	Cause	Solution
Links not saving	Missing RLS policy	Check INSERT policy in Supabase
Can't see my data	user_id mismatch	Check login session, RLS
Not redirecting to dashboard after login	Redirect URL error	Check Supabase Auth settings
Social login fails	OAuth config error	Check Callback URL, keys
Profile page 404	Username routing issue	Check dynamic routing setup

How to Check RLS Policies

-- Run in Supabase SQL Editor
SELECT * FROM pg_policies WHERE tablename = 'profiles';
SELECT * FROM pg_policies WHERE tablename = 'links';

Realtime/Analytics Issues

Symptom	Cause	Solution
Click count not increasing	clicks INSERT failure	Check RLS policy, table structure
Live preview not working	Realtime not enabled	Check Supabase Realtime settings
Analytics data slow	Missing index	Add index on clicked_at, link_id

Deployment/Operations Issues

Symptom	Cause	Solution
Vercel build fails	Type error or dependency	Test local build before pushing
Environment variables not reading	Not registered in Vercel	Settings → Environment Variables
CORS error	Origin not allowed	Use Next.js API routes (no CORS needed)
Stripe webhook fails	Signature verification error	Check raw body usage
Profile page slow	SSR not optimized	Apply ISR (Incremental Static Regeneration)

Correct Stripe Webhook Setup

// Next.js App Router
export async function POST(req: Request) {
  const body = await req.text(); // raw body
  const sig = req.headers.get('stripe-signature')!;
 
  const event = stripe.webhooks.constructEvent(
    body,
    sig,
    process.env.STRIPE_WEBHOOK_SECRET!
  );
 
  // Handle event...
}

Quick Solutions by Error Message

💡

"Module not found"

Run npm install

💡

"Port already in use"

Close server running in other terminal, or use a different port

💡

"ECONNREFUSED"

Check if server is running, verify URL is correct

💡

"Unauthorized" (401)

Check login status, check token expiration

💡

"Forbidden" (403)

Check RLS policies, check permissions

Solution for All Errors

Copy the entire error message and ask Claude "Explain why this error happened and how to fix it." Most issues get resolved!

B. FAQ Premium ↗