Troubleshooting

Running into issues while setting up Jiffoo Mall? This guide covers common problems and their solutions. Most issues can be resolved in under 5 minutes.

Quick Diagnosis

Before diving into specific issues, run this quick health check:

# Check Node.js version (need 18+)
node --version

# Check pnpm is installed
pnpm --version

# Verify database connection
pnpm --filter api db:status

# Check if ports are available
lsof -i :3000,3001,3002,3003

💡 Tip: Most issues fall into these categories: dependencies, database, ports, or environment configuration.

Installation Issues

Problem: `pnpm install` Fails

Symptoms:

Package installation errors
Peer dependency conflicts
Network timeout errors

Solutions:

# 1. Clear pnpm cache
pnpm store prune

# 2. Delete node_modules and lockfile
rm -rf node_modules pnpm-lock.yaml

# 3. Reinstall with verbose logging
pnpm install --verbose

# 4. If still failing, try with legacy peer deps
pnpm install --legacy-peer-deps

Alternative: Use npm instead:

npm install
npm run dev

Problem: Node Version Mismatch

Error message:

The engine "node" is incompatible with this module. Expected version ">=18.0.0"

Solution:

# Check current version
node --version

# Install Node 18+ using nvm
nvm install 18
nvm use 18

# Or install Node 20 (LTS)
nvm install 20
nvm use 20

# Verify installation
node --version  # Should show v18.x or v20.x

⚠️ Note: Jiffoo Mall requires Node.js 18 or higher.

Problem: Permission Denied Errors

Symptoms:

Cannot write to directories
EACCES errors during install

Solutions:

# Fix npm global permissions (Linux/Mac)
sudo chown -R $USER:$GROUP ~/.npm
sudo chown -R $USER:$GROUP ~/.pnpm-store

# Or use nvm to avoid permission issues
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

For Windows:

Run terminal as Administrator
Or use WSL2 for better compatibility

Database Issues

Problem: Database Connection Failed

Error message:

Error: connect ECONNREFUSED 127.0.0.1:5432

Diagnosis:

# Check if PostgreSQL is running
pg_isready

# Check database service status (Mac)
brew services list | grep postgresql

# Check database service status (Linux)
sudo systemctl status postgresql

Solutions:

Option 1: Start PostgreSQL

# Mac
brew services start postgresql

# Linux
sudo systemctl start postgresql

# Windows
net start postgresql-x64-14

Option 2: Use SQLite (Development Only)

Edit apps/api/.env:

DATABASE_URL="file:./dev.db"

Then regenerate:

pnpm --filter api db:generate
pnpm --filter api db:push

✓ Success check: pg_isready returns "accepting connections"

Problem: Database Migration Errors

Error message:

Migration failed: relation already exists

Solutions:

# Option 1: Reset database (DEVELOPMENT ONLY)
pnpm --filter api db:reset

# Option 2: Drop and recreate
pnpm --filter api db:drop
pnpm --filter api db:push

# Option 3: Check migration status
pnpm --filter api db:studio

⚠️ Warning: db:reset will delete all data. Use only in development!

Problem: Cannot Connect to Database URL

Symptoms:

Wrong database credentials
Invalid connection string format

Solution:

Verify your DATABASE_URL format in apps/api/.env:

PostgreSQL:

DATABASE_URL="postgresql://username:password@localhost:5432/database_name"

MySQL:

DATABASE_URL="mysql://username:password@localhost:3306/database_name"

SQLite:

DATABASE_URL="file:./dev.db"

Test connection:

# PostgreSQL
psql $DATABASE_URL -c "SELECT 1;"

# MySQL
mysql -h localhost -u username -p -e "SELECT 1;"

Service Startup Issues

Problem: Services Won't Start

Error message:

Error: listen EADDRINUSE: address already in use :::3000

Diagnosis:

# Check which process is using the ports
lsof -i :3000  # Shop
lsof -i :3001  # API
lsof -i :3002  # Super Admin
lsof -i :3003  # Admin

Solutions:

Option 1: Kill existing processes

# Kill all Node processes
killall node

# Or kill specific port
kill -9 $(lsof -t -i:3000)

Option 2: Change ports

Edit environment files:

# apps/shop/.env
PORT=3010

# apps/api/.env
PORT=3011

# apps/super-admin/.env
PORT=3012

# apps/admin/.env
PORT=3013

✓ Success check: All services start without errors

Problem: Build Fails During Startup

Error message:

Module not found: Can't resolve '@jiffoo/shared'

Solution:

# 1. Clean all build artifacts
pnpm clean

# 2. Rebuild shared packages
pnpm --filter @jiffoo/shared build

# 3. Rebuild all packages
pnpm build

# 4. Start dev servers
pnpm dev

Problem: Hot Reload Not Working

Symptoms:

Changes don't reflect in browser
Need to restart server after edits

Solutions:

# 1. Clear Next.js cache
rm -rf apps/shop/.next
rm -rf apps/admin/.next
rm -rf apps/super-admin/.next

# 2. Restart with clean cache
pnpm dev

For persistent issues:

Edit next.config.js:

module.exports = {
  webpack: (config) => {
    config.watchOptions = {
      poll: 1000,
      aggregateTimeout: 300,
    }
    return config
  }
}

Error message:

Invalid credentials

Solutions:

Option 1: Reset default admin

# Reset super admin credentials
pnpm --filter api db:seed --admin

# Default credentials:
# Email: [email protected]
# Password: admin123

Option 2: Create new admin user

# Using Prisma Studio
pnpm --filter api db:studio

# Navigate to User table and create new user
# Set role to "SUPER_ADMIN"

Option 3: Check JWT_SECRET

Verify apps/api/.env has:

JWT_SECRET="your-secret-key-minimum-32-characters-long"

🔐 Security: Always change default passwords in production!

Problem: Session Expires Immediately

Symptoms:

Logged out after page refresh
Token invalid errors

Solution:

Check environment variables:

# apps/api/.env
JWT_SECRET="your-secret-key-here"
JWT_EXPIRES_IN="7d"

# apps/admin/.env
NEXT_PUBLIC_API_URL="http://localhost:3001"

Test JWT generation:

# Run test script
pnpm --filter api test:auth

Problem: CORS Errors in Browser Console

Error message:

Access to fetch has been blocked by CORS policy

Solution:

Update apps/api/src/main.ts:

app.enableCors({
  origin: [
    'http://localhost:3000',
    'http://localhost:3002',
    'http://localhost:3003',
  ],
  credentials: true,
})

For development, allow all:

app.enableCors({
  origin: true,
  credentials: true,
})

Environment Configuration

Problem: Environment Variables Not Loading

Symptoms:

undefined values in application
Database connection fails with no error

Solution:

# 1. Verify .env files exist
ls apps/api/.env
ls apps/shop/.env
ls apps/admin/.env
ls apps/super-admin/.env

# 2. Copy from examples if missing
cp apps/api/.env.example apps/api/.env
cp apps/shop/.env.example apps/shop/.env
cp apps/admin/.env.example apps/admin/.env
cp apps/super-admin/.env.example apps/super-admin/.env

# 3. Restart servers
pnpm dev

Check variables are loaded:

# In apps/api/src/main.ts, temporarily add:
console.log('DATABASE_URL:', process.env.DATABASE_URL)

💡 Tip: Next.js requires NEXT_PUBLIC_ prefix for client-side variables

Problem: API URL Mismatch

Symptoms:

Frontend can't connect to backend
404 errors on API calls

Solution:

Ensure consistent URLs across apps:

# apps/api/.env
PORT=3001
API_URL="http://localhost:3001"

# apps/shop/.env
NEXT_PUBLIC_API_URL="http://localhost:3001"

# apps/admin/.env
NEXT_PUBLIC_API_URL="http://localhost:3001"

# apps/super-admin/.env
NEXT_PUBLIC_API_URL="http://localhost:3001"

Build & Dependency Issues

Problem: TypeScript Compilation Errors

Error message:

Type error: Cannot find module '@jiffoo/types'

Solution:

# 1. Build packages in correct order
pnpm --filter @jiffoo/types build
pnpm --filter @jiffoo/shared build
pnpm --filter @jiffoo/ui build

# 2. Or build all dependencies
pnpm build --filter=!./apps/*

# 3. Clear TypeScript cache
rm -rf node_modules/.cache
rm -rf apps/*/tsconfig.tsbuildinfo

Problem: Missing Shared Package

Error message:

Cannot find module '@jiffoo/shared' or its corresponding type declarations

Solution:

# 1. Verify workspace configuration
cat pnpm-workspace.yaml

# Should include:
# packages:
#   - 'apps/*'
#   - 'packages/*'

# 2. Reinstall workspace dependencies
pnpm install

# 3. Build shared packages
pnpm --filter @jiffoo/shared build

Problem: Out of Memory During Build

Error message:

FATAL ERROR: Ineffective mark-compacts near heap limit

Solution:

# Increase Node memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

# Or add to package.json scripts:
{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' pnpm build"
  }
}

Performance Issues

Problem: Slow Development Server

Symptoms:

Pages take long to load
Hot reload is very slow

Solutions:

# 1. Use turbo for faster builds
pnpm add -Dw turbo
pnpm turbo dev

# 2. Disable source maps in development
# next.config.js
module.exports = {
  productionBrowserSourceMaps: false,
}

# 3. Use SWC instead of Babel (Next.js default)
# Already enabled in Next.js 12+

Optimize for M1/M2 Macs:

# Use arm64 native packages
arch -arm64 pnpm install

Problem: Database Queries are Slow

Symptoms:

API responses take seconds
Admin panel loads slowly

Solutions:

# 1. Check for missing indexes
pnpm --filter api db:studio

# 2. Enable query logging
# apps/api/prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
  log      = ["query", "info", "warn", "error"]
}

# 3. Add indexes to frequently queried fields
# Example in schema.prisma:
model Product {
  id    String @id @default(cuid())
  name  String
  sku   String @unique

  @@index([name])
  @@index([sku])
}

Common Error Messages

`ERR_REQUIRE_ESM`

Error message:

require() of ES Module not supported

Solution:

Update package.json:

{
  "type": "module"
}

Or use dynamic imports:

// Instead of:
const module = require('module')

// Use:
const module = await import('module')

`Module parse failed: Unexpected token`

Error message:

Module parse failed: Unexpected token (1:0)
You may need an appropriate loader

Solution:

Update next.config.js:

module.exports = {
  webpack: (config) => {
    config.module.rules.push({
      test: /\.svg$/,
      use: ['@svgr/webpack'],
    })
    return config
  }
}

`Hydration failed`

Error message:

Error: Hydration failed because the initial UI does not match server-rendered

Solution:

# 1. Clear Next.js cache
rm -rf apps/*/.next

# 2. Check for client-only code in SSR
# Use dynamic imports for client-only components:

import dynamic from 'next/dynamic'

const ClientOnlyComponent = dynamic(
  () => import('./ClientOnlyComponent'),
  { ssr: false }
)

Still Having Issues?

Get Help

If none of these solutions work:

Check GitHub Issues: github.com/thefreelight/Jiffoo/issues
Join Discussions: github.com/thefreelight/Jiffoo/discussions
Read Full Docs: Installation Guide | Configuration

Create a Bug Report

When reporting issues, include:

# System information
node --version
pnpm --version
uname -a

# Package versions
pnpm list --depth=0

# Error logs
pnpm dev 2>&1 | tee error.log

Enable Debug Mode

# Set in apps/api/.env
LOG_LEVEL="debug"
DEBUG="jiffoo:*"

# Restart with verbose logging
pnpm dev

Preventive Measures

Regular Maintenance

Keep your installation healthy:

# Weekly: Update dependencies
pnpm update --latest

# Monthly: Clean and rebuild
pnpm clean && pnpm install && pnpm build

# Check for security issues
pnpm audit

Best Practices

✅ Use version control for .env templates (not actual secrets)
✅ Keep Node.js and pnpm updated
✅ Run migrations before updating code
✅ Test in development before deploying
✅ Monitor logs for early warning signs

Need more help? Check the Quick Start Guide or explore our Configuration Guide.

Troubleshooting

On this page