Troubleshooting

Common issues and solutions.

Installation & Setup

"Module not found" errors after cloning

Problem: Getting import errors or missing module errors.

Solution:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Port 5173 is already in use

Problem: Error: listen EADDRINUSE: address already in use :::5173

Solution:

# Kill process on port 5173
npx kill-port 5173
# Or use different port
pnpm dev --port 5174

Database Issues

MongoDB connection fails

Problem: MongooseError: connect ECONNREFUSED 127.0.0.1:27017

Solution:

• ensure MongoDB is running locally (mongosh) or check your connection string for Atlas.
• Check whitelist IP settings in Atlas.

Deployment Issues

Vercel deployment fails

Problem: Build fails on Vercel.

Solution:

• Check build logs.
• Verify environment variables are set in Vercel.
• Ensure dependencies are correctly listed in package.json.

Analytics Issues

Google Analytics is not tracking page views

Problem: No events appear in GA4 Realtime.

Solution:

• Set VITE_GA_MEASUREMENT_ID in your .env file with a valid GA4 ID (for example G-XXXXXXXXXX).
• Restart the dev server after changing environment variables.
• Confirm the ID is also set in your deployment environment.
• Disable ad blockers while testing analytics locally.
• Open browser devtools and verify requests to googletagmanager.com are not blocked.

Getting More Help

If you're still stuck, please open an issue on GitHub.