Troubleshooting Guide

Common issues and solutions

Overview

This guide provides comprehensive troubleshooting information for common issues encountered with the Portfolio OS system, including development, deployment, and automation problems.

📋 Table of Contents

Development Issues
Deployment Problems
Automation Issues
Performance Problems
Database Issues
Authentication Problems
Common Solutions
Emergency Procedures

🔧 Development Issues

Build Failures

Problem: Build process fails with TypeScript errors

Error: Type 'string' is not assignable to type 'number'

Solutions:

Check TypeScript Configuration
```
npx tsc --noEmit
```

Clear Cache and Rebuild

rm -rf .next node_modules
pnpm install
pnpm build

Update Dependencies
```
pnpm update
```

Problem: Module not found errors

Module not found: Can't resolve '@/components/Button'

Solutions:

Check Import Paths

// Correct
import { Button } from '@/components/Button';

// Check tsconfig.json paths
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Verify File Structure

# Ensure files exist
ls -la src/components/Button.tsx

Development Server Issues

Problem: Development server won't start

Error: Port 3000 is already in use

Solutions:

Kill Process on Port

# Find process using port
lsof -ti:3000

# Kill process
kill -9 $(lsof -ti:3000)

Use Different Port
```
pnpm dev --port 3001
```

Check Environment Variables

# Verify .env.local exists
ls -la .env.local

# Check for syntax errors
cat .env.local

Problem: Hot reload not working

Solutions:

Clear Next.js Cache
```
rm -rf .next
pnpm dev
```

Check File Watchers

# Increase file watcher limit (Linux/Mac)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Dependency Issues

Problem: Package installation fails

Error: EACCES: permission denied

Solutions:

Fix Permissions
```
sudo chown -R $(whoami) ~/.npm
```
Use PNPM
```
npm install -g pnpm
pnpm install
```

Clear Package Manager Cache

# PNPM
pnpm store prune

# NPM
npm cache clean --force

🚀 Deployment Problems

Vercel Deployment Issues

Problem: Build fails on Vercel

Build failed: Command "pnpm build" exited with 1

Solutions:

Check Build Logs
- Go to Vercel Dashboard â†’ Deployments
- Click on failed deployment
- Review build logs for specific errors

Update Build Command

// vercel.json
{
  "buildCommand": "pnpm build",
  "installCommand": "pnpm install"
}

Environment Variables
- Verify all required env vars are set in Vercel
- Check for typos in variable names
- Ensure production values are correct

Problem: Environment variables not loading

Solutions:

Check Vercel Environment Settings
- Dashboard â†’ Project â†’ Settings â†’ Environment Variables
- Ensure variables are set for Production environment

Verify Variable Names

# Check in code
console.log(process.env.NEXT_PUBLIC_API_URL);

Redeploy After Changes
- Environment variable changes require new deployment
- Trigger redeploy manually if needed

Database Connection Issues

Problem: Database connection fails

Error: connect ECONNREFUSED 127.0.0.1:5432

Solutions:

Check Database URL

# Verify DATABASE_URL format
echo $DATABASE_URL
# Should be: postgresql://user:password@host:port/database

Test Connection

# Using psql
psql $DATABASE_URL

# Using Prisma
npx prisma db push

Check Database Status

# For local PostgreSQL
sudo service postgresql status
sudo service postgresql start

ðŸ¤– Automation Issues

PowerShell Script Problems

Problem: Execution policy prevents script running

Execution of scripts is disabled on this system

Solutions:

Set Execution Policy

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Run Script Directly

powershell -ExecutionPolicy Bypass -File script.ps1

Check Script Permissions
```
Get-ExecutionPolicy -List
```

Problem: Git commands fail in automation

fatal: not a git repository

Solutions:

Check Working Directory

# Ensure you're in project root
Get-Location
Set-Location "C:\path\to\portfolio-os"

Verify Git Repository
```
git status
git remote -v
```
Check Git Configuration
```
git config --list
```

Housekeeping Script Issues

Problem: File organization fails

Move-Item: Cannot create a file when that file already exists

Solutions:

Check for Conflicts

# List files in target directory
Get-ChildItem "scripts\utilities" -Name

Use Force Flag

Move-Item $file.FullName $targetDir -Force

Backup Before Moving

Copy-Item $file.FullName $backupPath
Move-Item $file.FullName $targetDir

âš¡ Performance Problems

Slow Loading Times

Problem: Site loads slowly

Solutions:

Optimize Images

# Use Next.js Image component
import Image from 'next/image';

<Image
  src="/image.jpg"
  alt="Description"
  width={800}
  height={600}
  priority
/>

Enable Compression

// next.config.js
module.exports = {
  compress: true,
  poweredByHeader: false,
};

Check Bundle Size

pnpm build
# Review bundle analyzer output

Database Performance

Problem: Slow database queries

Solutions:

Add Database Indexes

CREATE INDEX idx_posts_published_at ON posts(published_at);
CREATE INDEX idx_projects_status ON projects(status);

Optimize Queries

// Use select to limit fields
const projects = await prisma.project.findMany({
  select: {
    id: true,
    title: true,
    description: true,
  },
  where: {
    status: 'published'
  }
});

Enable Query Logging

// prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  log      = ["query", "info", "warn", "error"]
}

ðŸ—„ï¸ Database Issues

Migration Problems

Problem: Migration fails

Error: Migration failed

Solutions:

Reset Database

npx prisma migrate reset
npx prisma generate

Check Migration Status
```
npx prisma migrate status
```
Manual Migration
```
npx prisma db push
```

Connection Pool Issues

Problem: Too many connections

Error: too many connections

Solutions:

Configure Connection Pool

// prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  relationMode = "prisma"
}

Use Connection Pooling

# Add to DATABASE_URL
postgresql://user:password@host:port/database?connection_limit=5

ðŸ” Authentication Problems

Problem: Cannot log into dashboard

Solutions:

Check Credentials
- Verify username and password
- Check for typos
- Ensure account is active
Clear Browser Data
- Clear cookies and cache
- Try incognito/private mode
- Check browser console for errors

Reset Password

# Use password reset functionality
# Or reset in database directly

Session Problems

Problem: Session expires too quickly

Solutions:

Check Session Configuration

// auth configuration
const authOptions = {
  session: {
    strategy: 'jwt',
    maxAge: 30 * 24 * 60 * 60, // 30 days
  }
};

Implement Refresh Tokens

// Add refresh token logic
const refreshToken = await generateRefreshToken(userId);

ðŸ› ï¸ Common Solutions

General Troubleshooting Steps

Check Logs

# Application logs
tail -f logs/app.log

# System logs
journalctl -u your-service

Verify Environment

# Check Node.js version
node --version

# Check PNPM version
pnpm --version

# Check environment variables
env | grep -E "(NODE|DATABASE|API)"

Clear Caches

# Clear all caches
rm -rf .next node_modules .turbo
pnpm install
pnpm build

Debugging Tools

Enable Debug Logging
```
DEBUG=* pnpm dev
```
Use Browser DevTools
- Network tab for API calls
- Console for JavaScript errors
- Performance tab for bottlenecks

Database Debugging

# Enable Prisma logging
npx prisma studio

ðŸš¨ Emergency Procedures

Site Down

Check Status

# Check if site is accessible
curl -I https://johnschibelli.dev

# Check Vercel status
# Visit status.vercel.com

Rollback Deployment
- Go to Vercel Dashboard
- Find last working deployment
- Click "Promote to Production"

Database Recovery

# Restore from backup
pg_restore -d database_name backup_file.sql

Data Loss

Check Backups

# List available backups
ls -la backups/

Restore Data

# Restore database
psql $DATABASE_URL < backup.sql

Verify Integrity

# Check data integrity
npx prisma db push

ðŸ“ž Getting Help

Self-Service Resources

Documentation
- Check this troubleshooting guide
- Review API documentation
- Read developer guides
Community Support
- GitHub Discussions
- Stack Overflow
- Discord/Slack channels
Professional Support
- Create GitHub issue
- Contact development team
- Schedule consultation

Issue Reporting

When reporting issues, include:

Error Messages: Full error text and stack traces
Steps to Reproduce: Detailed reproduction steps
Environment: OS, Node.js version, browser
Logs: Relevant log files and console output
Screenshots: Visual evidence of the problem

This troubleshooting guide helps resolve common issues and maintain system stability! 🔧

Troubleshooting

Common Issues

Troubleshooting Guide

Overview

📋 Table of Contents

🔧 Development Issues

Build Failures

Problem: Build process fails with TypeScript errors

Problem: Module not found errors

Development Server Issues

Problem: Development server won't start

Problem: Hot reload not working

Dependency Issues

Problem: Package installation fails

🚀 Deployment Problems

Vercel Deployment Issues

Problem: Build fails on Vercel

Problem: Environment variables not loading

Database Connection Issues

Problem: Database connection fails

ðŸ¤– Automation Issues

PowerShell Script Problems

Problem: Execution policy prevents script running

Problem: Git commands fail in automation

Housekeeping Script Issues

Problem: File organization fails

âš¡ Performance Problems

Slow Loading Times

Problem: Site loads slowly

Database Performance

Problem: Slow database queries

ðŸ—„ï¸ Database Issues

Migration Problems

Problem: Migration fails

Connection Pool Issues

Problem: Too many connections

ðŸ” Authentication Problems

Login Issues

Problem: Cannot log into dashboard

Session Problems

Problem: Session expires too quickly

ðŸ› ï¸ Common Solutions

General Troubleshooting Steps

Debugging Tools

ðŸš¨ Emergency Procedures

Site Down

Data Loss

ðŸ“ž Getting Help

Self-Service Resources

Issue Reporting

ðŸ—„ï¸ Database Issues

ðŸ” Authentication Problems

ðŸ› ï¸ Common Solutions