Troubleshooting Guide

Installation Issues

Node.js Not Found

Symptoms: Command node --version returns "command not found"

Solutions:

1. Verify Node.js is installed: Download from nodejs.org
2. Check if Node.js is in PATH:

   echo $PATH

3. Restart your terminal/command prompt after installation
4. On Windows: Restart your computer if PATH changes don't take effect

npm Command Not Found

Symptoms: Command npm --version returns "command not found"

Solutions:

1. npm comes bundled with Node.js - reinstall Node.js if npm is missing
2. Verify npm installation:

   npm --version

3. Update npm to latest version:

   npm install -g npm@latest

MySQL Not Installed or Not Running

Symptoms: Database connection errors, "ECONNREFUSED"

Solutions:

1. Windows: Check Services (services.msc) - MySQL service should be running
2. Linux: Check service status:

   sudo systemctl status mysql

3. macOS: Check if MySQL is running:

   brew services list

4. Start MySQL service if stopped

Database Connection Problems

Error: "Access denied for user"

Symptoms: Authentication failed when connecting to MySQL

Solutions:

1. Verify credentials in server/.env file match your MySQL setup
2. Check username and password are correct (no extra spaces)
3. Test connection manually:

   mysql -u root -p

4. Reset MySQL root password if forgotten (platform-specific instructions)

Error: "Unknown database"

Symptoms: Error: "Unknown database 'managex_db'"

Solutions:

1. Create the database manually:

   mysql -u root -p
   CREATE DATABASE managex_db;

2. Or update DB_NAME in .env to match an existing database
3. Verify database exists:

   SHOW DATABASES;

Error: "Can't connect to MySQL server"

Symptoms: Connection timeout or refused

Solutions:

1. Verify MySQL service is running (see Installation Issues above)
2. Check DB_HOST in .env - should be localhost for local installations
3. Verify DB_PORT - default is 3306
4. Check firewall settings if using remote MySQL server
5. Test connection:

   mysql -h localhost -P 3306 -u root -p

Migration Errors

Error: "Migration failed"

Symptoms: npm run db:migrate fails with errors

Solutions:

1. Ensure database exists and is accessible
2. Check database user has CREATE, ALTER, and DROP permissions
3. Verify MySQL is running
4. Check migration status:

   npm run db:migrate:status

5. Review error messages for specific table/column issues

Error: "Table already exists"

Symptoms: Migration tries to create tables that already exist

Solutions:

1. Check migration status to see which migrations have run
2. If starting fresh, drop and recreate database:

   DROP DATABASE managex_db;
   CREATE DATABASE managex_db;

3. Or undo all migrations and re-run:

   npm run db:migrate:undo:all
   npm run db:migrate

Error: "SequelizeConnectionError"

Symptoms: Cannot connect to database during migration

Solutions:

1. Verify database connection settings in .env
2. Ensure MySQL service is running
3. Test connection manually (see Database Connection Problems)
4. Check config/config.js is reading environment variables correctly

Seeder Issues

Error: "Seeder failed"

Symptoms: npm run demo fails with errors

Solutions:

1. Ensure migrations have completed successfully first
2. Verify IS_DEMO is set correctly in .env (0 or 1)
3. Check that required tables exist:

   SHOW TABLES;

4. Review error messages for specific seeder issues
5. Some seeders depend on others - ensure they run in order

Error: "Foreign key constraint fails"

Symptoms: Seeder fails due to missing referenced records

Solutions:

1. Ensure all prerequisite seeders have run (organization, roles, etc.)
2. Run seeders in correct order - use npm run demo which handles order
3. If manually running seeders, check dependencies
4. Verify parent records exist before creating child records

IS_DEMO Configuration Issues

Symptoms: Wrong seeders running or demo data missing

Solutions:

1. Check IS_DEMO value in .env:
   • IS_DEMO=0 - Runs only non-demo seeders (production)
   • IS_DEMO=1 - Runs all seeders including demo data
2. Ensure no spaces around the equals sign: IS_DEMO=0 not IS_DEMO = 0
3. Restart terminal/command prompt after changing .env
4. Verify the value is being read correctly by checking console output

Server Startup Problems

Error: "Cannot find module"

Symptoms: Server fails to start with module not found errors

Solutions:

1. Install dependencies:

   cd server
   npm install

2. Delete node_modules and package-lock.json, then reinstall:

   rm -rf node_modules package-lock.json
   npm install

3. Verify you're in the correct directory (server folder)

Error: "EADDRINUSE" or Port Already in Use

Symptoms: Server cannot start because port is occupied

Solutions:

1. Change PORT in .env to an available port (e.g., 3001, 3002)
2. Or kill the process using the port (see Port Conflicts section below)

Error: "JWT_SECRET is not defined"

Symptoms: Server fails with JWT secret errors

Solutions:

1. Ensure JWT_SECRET is set in server/.env
2. Verify no syntax errors in .env file
3. Check for missing quotes or special characters
4. Restart server after updating .env

Server Starts But Shows Errors

Symptoms: Server runs but displays warnings or errors in console

Solutions:

1. Check error messages for specific issues
2. Verify all environment variables are set correctly
3. Check database connection is working
4. Review server logs for detailed error information

Port Conflicts

Finding Process Using a Port (Windows)

netstat -ano | findstr :3000

This shows the PID (Process ID) of the process using port 3000.

Killing Process on Windows

taskkill /PID <PID> /F

Replace <PID> with the actual Process ID from the previous command.

Finding Process Using a Port (Linux/macOS)

lsof -i :3000

Or using netstat:

netstat -tulpn | grep :3000

Killing Process on Linux/macOS

kill -9 <PID>

Replace <PID> with the actual Process ID.

Permission Errors

Permission Denied on Windows

Symptoms: "Access is denied" or "Permission denied" errors

Solutions:

1. Run Command Prompt or PowerShell as Administrator:
   • Right-click on Command Prompt/PowerShell
   • Select "Run as administrator"
2. For file operations, ensure you have write permissions in the project directory
3. Check Windows User Account Control (UAC) settings

Permission Denied on Linux/macOS

Symptoms: "Permission denied" or "EACCES" errors

Solutions:

1. Use sudo for system-level operations (use with caution)
2. Fix file permissions:

   chmod -R 755 server

3. Change ownership if needed:

   sudo chown -R $USER:$USER server

4. Avoid running npm install with sudo (can cause permission issues)

Database Permission Errors

Symptoms: Cannot create database, tables, or execute migrations

Solutions:

1. Ensure database user has necessary permissions:

   GRANT ALL PRIVILEGES ON managex_db.* TO 'username'@'localhost';
   FLUSH PRIVILEGES;

2. Or use root user for development (not recommended for production)
3. Verify user can connect and create objects

Dependency Issues

npm install Fails

Symptoms: Errors during npm install

Solutions:

1. Clear npm cache:

   npm cache clean --force

2. Delete node_modules and package-lock.json:

   rm -rf node_modules package-lock.json

3. Reinstall dependencies:

   npm install

4. Update npm to latest version:

   npm install -g npm@latest

5. Check Node.js version compatibility (Node 16+ required)

Module Version Conflicts

Symptoms: Warnings about peer dependencies or version mismatches

Solutions:

1. Update all dependencies:

   npm update

2. Check for outdated packages:

   npm outdated

3. Review package.json for version constraints
4. Most warnings are non-critical - test if application still works

Native Module Compilation Errors

Symptoms: Errors about building native modules (bcrypt, etc.)

Solutions:

1. Windows: Install Windows Build Tools:

   npm install -g windows-build-tools

2. Linux: Install build essentials:

   sudo apt-get install build-essential

3. macOS: Install Xcode Command Line Tools:

   xcode-select --install

Verification Steps

Complete System Check

Follow these steps to verify your installation is working correctly:

1. Verify Prerequisites

# Check Node.js version (should be 16+)
node --version

# Check npm version (should be 8+)
npm --version

# Check MySQL version
mysql --version

2. Verify Database

# Connect to MySQL
mysql -u root -p

# Check database exists
SHOW DATABASES;

# Use your database
USE managex_db;

# Check tables exist
SHOW TABLES;

# Exit MySQL
EXIT;

3. Verify Environment Configuration

Check that server/.env file exists and contains:

• Database configuration (DB_HOST, DB_NAME, DB_USERNAME, DB_PASSWORD)
• JWT secrets (JWT_SECRET, JWT_REFRESH_SECRET)
• Port configuration (PORT)
• IS_DEMO setting

4. Verify Dependencies

# Navigate to server directory
cd server

# Check node_modules exists
ls node_modules

# Verify key packages
npm list express sequelize mysql2

5. Verify Server Startup

# Start server
npm run dev

# Should see:
# Server running on port 3000 (or your configured port)
# Database connected successfully

6. Verify Application Access

1. Open browser and navigate to http://localhost:3000
2. Should see login page
3. Login with default credentials:
   • Email: superadmin@managex.com
   • Password: SuperAdmin@123

Still Need Help?

If you've tried all the solutions above and still encounter issues:

• Review error messages carefully - they often contain specific clues
• Check the application logs for detailed error information
• Verify all prerequisites are installed and up to date
• Ensure you're following the setup guide for your operating system
• Check that your system meets the minimum requirements