Installation Problems

Comprehensive guide to resolving installation and setup issues across different environments.

Installation Problems

This section addresses issues that occur during the initial installation and setup process, including dependency management, environment configuration, and platform-specific problems.

Node.js Version Issues

Issue: Node.js version incompatibility

Symptoms:

  • Installation fails with version errors
  • Runtime errors due to unsupported features
  • Package compatibility warnings
  • Build process failures

Solutions:

# Check current Node.js version
node --version
npm --version

# Required: Node.js 18.0 or higher
# Install correct version using nvm (recommended)

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install nvm (Windows)
# Download and install from: https://github.com/coreybutler/nvm-windows

# Install and use Node.js 18
nvm install 18
nvm use 18
nvm alias default 18

# Verify installation
node --version  # Should show v18.x.x or higher
npm --version   # Should show compatible npm version

Version Management:

# List available Node.js versions
nvm list available  # Windows
nvm ls-remote       # macOS/Linux

# List installed versions
nvm list           # Windows
nvm ls             # macOS/Linux

# Switch between versions
nvm use 16.20.0
nvm use 18.19.0

# Set default version
nvm alias default 18.19.0

# Check which version is currently active
nvm current
which node

Alternative Installation Methods:

# Direct download (not recommended for development)
# Visit: https://nodejs.org/en/download/

# Package managers
# macOS with Homebrew
brew install node@18
brew link --force node@18

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL/Fedora
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo dnf install nodejs npm

Package Manager Issues

Issue: npm/pnpm installation fails

Symptoms:

  • Package installation errors
  • Dependency resolution conflicts
  • Network timeout errors
  • Permission denied errors

npm Troubleshooting:

# Clear npm cache
npm cache clean --force

# Verify cache integrity
npm cache verify

# Delete node_modules and reinstall
rm -rf node_modules
rm package-lock.json
npm install

# Use legacy peer deps (for compatibility issues)
npm install --legacy-peer-deps

# Install with force (use cautiously)
npm install --force

# Check npm configuration
npm config list
npm config get registry

# Fix registry issues
npm config set registry https://registry.npmjs.org/

# Increase timeout for slow networks
npm config set timeout 60000

pnpm Troubleshooting:

# Install pnpm globally
npm install -g pnpm

# Clear pnpm cache
pnpm store prune

# Install dependencies
pnpm install

# Force reinstall
pnpm install --force

# Shamefully hoist (for compatibility)
pnpm install --shamefully-hoist

# Check pnpm configuration
pnpm config list

# Set registry
pnpm config set registry https://registry.npmjs.org/

Yarn Troubleshooting:

# Install Yarn globally
npm install -g yarn

# Clear Yarn cache
yarn cache clean

# Install dependencies
yarn install

# Force reinstall
yarn install --force

# Check integrity
yarn check --integrity

# Set registry
yarn config set registry https://registry.npmjs.org/

Issue: Dependency conflicts

Symptoms:

  • Peer dependency warnings
  • Version mismatch errors
  • Conflicting package versions
  • Module resolution failures

Solutions:

# Check for dependency conflicts
npm ls
npm outdated

# Find duplicate packages
npm ls --depth=0 | grep -E "UNMET|invalid"

# Resolve peer dependencies
npm install --legacy-peer-deps

# Update specific packages
npm update package-name
npm install package-name@latest

# Check which packages depend on a specific package
npm ls package-name

# Deduplicate dependencies
npm dedupe

Manual Dependency Resolution:

// package.json - Add overrides for conflicting dependencies
{
  "overrides": {
    "react": "^18.0.0",
    "@types/react": "^18.0.0"
  },
  "resolutions": {
    "react": "^18.0.0",
    "@types/react": "^18.0.0"
  }
}

Permission Issues

Issue: Permission denied errors (EACCES)

Symptoms:

  • EACCES errors during npm install
  • Cannot write to directories
  • Global package installation failures
  • File system permission errors

macOS/Linux Solutions:

# Method 1: Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to ~/.bashrc or ~/.zshrc
export PATH=~/.npm-global/bin:$PATH
source ~/.bashrc

# Method 2: Change npm's default directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

# Method 3: Use nvm (recommended)
# Install and use nvm as shown above

# Method 4: Fix ownership (use cautiously)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Fix project directory permissions
sudo chown -R $(whoami) .

Windows Solutions:

# Run PowerShell or Command Prompt as Administrator
# Right-click -> "Run as administrator"

# Or use Windows Subsystem for Linux (WSL)
wsl --install
wsl --set-default-version 2

# Install Node.js in WSL
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Issue: Corporate firewall/proxy

Symptoms:

  • Network timeout errors
  • SSL certificate errors
  • Registry connection failures
  • Package download failures

Solutions:

# Configure npm proxy
npm config set proxy http://proxy-server:port
npm config set https-proxy http://proxy-server:port

# Skip SSL verification (not recommended for production)
npm config set strict-ssl false

# Use corporate registry
npm config set registry http://your-corporate-registry.com

# Set certificate authority
npm config set cafile /path/to/certificate.crt

# Check network connectivity
curl -I https://registry.npmjs.org/
ping registry.npmjs.org

# Use different registry
npm install --registry https://registry.npmjs.org/

Platform-Specific Issues

macOS Issues

Issue: Xcode Command Line Tools missing

# Install Xcode Command Line Tools
xcode-select --install

# Verify installation
xcode-select -p

# If issues persist, reinstall
sudo xcode-select --reset
xcode-select --install

Issue: M1/M2 Compatibility

# Use Rosetta for x86 packages (if needed)
arch -x86_64 npm install

# Check architecture
uname -m  # Should show arm64 for M1/M2

# Install native ARM packages when available
npm install --target_arch=arm64

Windows Issues

Issue: Build tools missing

# Install Windows Build Tools
npm install --global windows-build-tools

# Or install Visual Studio Build Tools manually
# Download from: https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022

# Install Python (required for some native modules)
npm install --global --production windows-build-tools --vs2015

# Alternative: Use chocolatey
choco install visualstudio2022buildtools
choco install python

Issue: Path length limitations

# Enable long paths in Windows 10/11
# Run as Administrator in PowerShell
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

# Or use shorter paths
# Move project to C:\dev\project instead of deep nested folders

Linux Issues

Issue: Missing build dependencies

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential python3-dev

# CentOS/RHEL/Fedora
sudo dnf install gcc gcc-c++ make python3-devel
# or
sudo yum install gcc gcc-c++ make python3-devel

# Alpine Linux
apk add --no-cache make gcc g++ python3 python3-dev

Issue: File watching limits

# Increase inotify limits (for file watching)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Temporary increase
sudo sysctl fs.inotify.max_user_watches=524288

# Check current limits
cat /proc/sys/fs/inotify/max_user_watches

Environment Setup Issues

Issue: Environment file configuration

Symptoms:

  • Environment variables not loading
  • Different behavior in development vs production
  • Configuration errors

Solutions:

# Create proper environment file structure
touch .env.local          # Local development (highest priority)
touch .env.development     # Development environment
touch .env.production      # Production environment
touch .env.example         # Template for team

# Check file permissions
ls -la .env*

# Ensure files are not committed to git
echo ".env.local" >> .gitignore
echo ".env*.local" >> .gitignore

Environment File Template:

# .env.example
# Copy this file to .env.local and fill in your values

# Database
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# Authentication
NEXTAUTH_SECRET=your_nextauth_secret
NEXTAUTH_URL=http://localhost:3000

# External APIs
STRIPE_SECRET_KEY=your_stripe_secret_key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your_stripe_publishable_key

# Email
RESEND_API_KEY=your_resend_api_key

# Storage
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_api_secret

Issue: Git configuration

Symptoms:

  • Cannot clone repository
  • Authentication failures
  • SSL certificate errors

Solutions:

# Configure Git user
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set up SSH key
ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Add public key to GitHub/GitLab
cat ~/.ssh/id_ed25519.pub

# Test SSH connection
ssh -T git@github.com

# Configure Git for corporate networks
git config --global http.proxy http://proxy-server:port
git config --global https.proxy http://proxy-server:port

# Skip SSL verification (not recommended)
git config --global http.sslVerify false

Database Setup Issues

Issue: Supabase project setup

Symptoms:

  • Cannot connect to Supabase
  • Invalid project URL
  • Authentication errors

Solutions:

# Install Supabase CLI
npm install -g @supabase/cli

# Login to Supabase
supabase login

# Initialize project
supabase init

# Link to existing project
supabase link --project-ref your-project-ref

# Generate types
supabase gen types typescript --linked > types/database.types.ts

# Check connection
supabase status

Manual Supabase Setup:

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!
const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!

if (!supabaseUrl || !supabaseAnonKey) {
  throw new Error('Missing Supabase environment variables')
}

export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: true
  }
})

// Test connection
export async function testSupabaseConnection() {
  try {
    const { data, error } = await supabase
      .from('users')
      .select('count')
      .limit(1)
    
    if (error) throw error
    console.log('✅ Supabase connection successful')
    return true
  } catch (error) {
    console.error('❌ Supabase connection failed:', error)
    return false
  }
}

Installation Validation

Complete Setup Verification

#!/bin/bash
# setup-verification.sh

echo "🔍 Setup Verification"
echo "===================="

# Check Node.js version
NODE_VERSION=$(node --version)
echo "Node.js: $NODE_VERSION"

if [[ "$NODE_VERSION" < "v18.0.0" ]]; then
  echo "❌ Node.js version must be 18.0.0 or higher"
  exit 1
fi

# Check npm version
NPM_VERSION=$(npm --version)
echo "npm: $NPM_VERSION"

# Check if project dependencies are installed
if [ ! -d "node_modules" ]; then
  echo "❌ node_modules not found. Run 'npm install'"
  exit 1
fi

# Check for essential files
FILES=(".env.local" "package.json" "next.config.mjs" "tsconfig.json")
for file in "${FILES[@]}"; do
  if [ -f "$file" ]; then
    echo "✅ $file exists"
  else
    echo "⚠️  $file not found"
  fi
done

# Check environment variables
if [ -f ".env.local" ]; then
  echo "✅ Environment file exists"
  
  # Check for required variables
  if grep -q "NEXT_PUBLIC_SUPABASE_URL" .env.local; then
    echo "✅ NEXT_PUBLIC_SUPABASE_URL configured"
  else
    echo "❌ NEXT_PUBLIC_SUPABASE_URL missing"
  fi
  
  if grep -q "NEXT_PUBLIC_SUPABASE_ANON_KEY" .env.local; then
    echo "✅ NEXT_PUBLIC_SUPABASE_ANON_KEY configured"
  else
    echo "❌ NEXT_PUBLIC_SUPABASE_ANON_KEY missing"
  fi
fi

# Try to build project
echo ""
echo "🔨 Testing build..."
if npm run build > /dev/null 2>&1; then
  echo "✅ Build successful"
else
  echo "❌ Build failed"
  echo "Run 'npm run build' to see detailed errors"
fi

echo ""
echo "✅ Setup verification complete!"

Automated Setup Script

#!/bin/bash
# auto-setup.sh

echo "🚀 Automated Setup"
echo "=================="

# Check if Node.js is installed
if ! command -v node &> /dev/null; then
  echo "❌ Node.js not found. Please install Node.js 18+ first."
  exit 1
fi

# Check Node.js version
NODE_VERSION=$(node --version | cut -d 'v' -f 2)
REQUIRED_VERSION="18.0.0"

if [ "$(printf '%s\n' "$REQUIRED_VERSION" "$NODE_VERSION" | sort -V | head -n1)" != "$REQUIRED_VERSION" ]; then
  echo "❌ Node.js version $NODE_VERSION is too old. Please upgrade to 18.0.0 or higher."
  exit 1
fi

echo "✅ Node.js version $NODE_VERSION is compatible"

# Install dependencies
echo "📦 Installing dependencies..."
npm install

# Copy environment file
if [ ! -f ".env.local" ] && [ -f ".env.example" ]; then
  echo "📄 Creating .env.local from .env.example"
  cp .env.example .env.local
  echo "⚠️  Please edit .env.local with your actual values"
fi

# Generate Supabase types (if CLI is available)
if command -v supabase &> /dev/null; then
  echo "🔄 Generating Supabase types..."
  supabase gen types typescript --linked > types/database.types.ts 2>/dev/null || echo "⚠️  Could not generate types. Make sure Supabase is linked."
fi

# Test build
echo "🔨 Testing build..."
if npm run build; then
  echo "✅ Setup complete! Run 'npm run dev' to start development."
else
  echo "❌ Build failed. Please check the errors above."
fi

This comprehensive installation troubleshooting guide covers the most common setup issues across different platforms and provides automated solutions for quick resolution.