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!