Troubleshooting Installation

Common installation issues and their solutions.

Troubleshooting Installation

This guide covers common issues you might encounter during installation and setup, along with their solutions.

Common Installation Issues

Environment Variables Not Loading

Symptoms:

  • Application fails to connect to Supabase
  • Environment variables appear undefined in the browser console

Solutions:

  • Ensure .env.local is in the root directory of your project
  • Restart the development server after changing environment variables
  • Check that variable names start with NEXT_PUBLIC_ for client-side access
  • Verify there are no syntax errors in your .env.local file

Supabase Connection Issues

Symptoms:

  • "Failed to connect to Supabase" error messages
  • Authentication not working properly

Solutions:

  • Verify your Supabase URL and API key are correct
  • Check if your Supabase project is active and running
  • Ensure you're using the correct environment (development/production)
  • Test the connection by visiting your Supabase project dashboard

Build Errors

Symptoms:

  • TypeScript compilation errors
  • Build process fails with module resolution errors

Solutions:

  • Clear Next.js cache: rm -rf .next
  • Clear node_modules and reinstall: rm -rf node_modules && pnpm install
  • Check TypeScript errors: pnpm build
  • Verify all dependencies are properly installed

Authentication Issues

Symptoms:

  • Users cannot sign in or sign up
  • Redirect loops after authentication
  • "Invalid redirect URL" errors

Solutions:

  • Verify redirect URLs in Supabase Authentication settings
  • Check browser console for authentication errors
  • Ensure cookies are enabled in the browser
  • Confirm Site URL is correctly configured in Supabase

Database Issues

Migration Failures

Symptoms:

  • Database schema not created properly
  • SQL execution errors during setup

Solutions:

  • Check SQL syntax in migration files
  • Verify database permissions and user roles
  • Review Supabase logs for detailed error messages
  • Ensure your database user has sufficient privileges

RLS Policy Issues

Symptoms:

  • Users cannot access data they should have permission to see
  • "Row Level Security policy violation" errors

Solutions:

  • Ensure Row Level Security policies are correctly configured
  • Check user permissions and roles in the database
  • Review policy conditions and logic
  • Test policies with different user scenarios

Performance Issues

Slow Loading

Symptoms:

  • Application takes a long time to load
  • Large bundle sizes affecting performance

Solutions:

  • Enable bundle analysis to identify large dependencies: pnpm analyze
  • Implement lazy loading for heavy components
  • Optimize images and assets
  • Consider code splitting for large modules

Memory Issues

Symptoms:

  • Browser becomes unresponsive
  • High memory usage in development tools
  • Application crashes with out-of-memory errors

Solutions:

  • Check for memory leaks in React components
  • Implement proper cleanup in useEffect hooks
  • Monitor browser developer tools for memory usage
  • Use React DevTools Profiler to identify performance bottlenecks

Development Environment Issues

Port Already in Use

Symptoms:

  • "Port 3000 is already in use" error when starting development server

Solutions:

  • Kill existing processes using the port: netstat -ano | findstr :3000 (Windows)
  • Use a different port: pnpm dev -- -p 3001
  • Restart your computer to clear all processes

SSL Certificate Issues (HTTPS Development)

Symptoms:

  • Browser shows security warnings
  • Camera/microphone features not working in development

Solutions:

  • Regenerate SSL certificates in the certs/ directory
  • Add certificates to your system's trusted certificate store
  • Use pnpm dev:https for HTTPS development mode

Package Manager Issues

Package Installation Failures

Symptoms:

  • pnpm install fails with permission errors
  • Dependency conflicts during installation

Solutions:

  • Clear package manager cache: pnpm store prune
  • Delete lock file and reinstall: rm -rf pnpm-lock.yaml && pnpm install
  • Use npm if pnpm continues to fail: npm install
  • Check for conflicting global packages

Version Compatibility Issues

Symptoms:

  • Package version conflicts
  • Peer dependency warnings

Solutions:

  • Update Node.js to the recommended version (18.0+)
  • Update pnpm to the latest version: npm install -g pnpm@latest
  • Check for outdated dependencies: pnpm outdated
  • Review package.json for version conflicts

Getting Help

If you continue to experience issues after trying these solutions:

  1. Check the Console: Look for error messages in your browser's developer console
  2. Review Logs: Check both application logs and Supabase logs for detailed error information
  3. Search Documentation: Review the complete documentation for additional guidance
  4. Community Support: Check the project's GitHub issues or community forums
  5. Create an Issue: If you've found a bug, create a detailed issue report with:
    • Your operating system and version
    • Node.js and package manager versions
    • Complete error messages
    • Steps to reproduce the issue

Preventive Measures

To avoid future installation issues:

  • Keep your Node.js and package manager updated
  • Regularly update dependencies
  • Use consistent environments across development and production
  • Document any custom configurations or modifications
  • Maintain proper backup procedures for your development environment