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.