Troubleshooting Guide

Common issues and solutions for AsseTrack

Installation Issues

Node.js Installation Problems

Symptoms: "node: command not found", "npm: command not found"
Solution: Verify Node.js installation and PATH configuration
  1. Check if Node.js is installed: node --version
  2. If not installed, follow the platform-specific installation guide
  3. Verify PATH environment variable includes Node.js directory
  4. Restart terminal/command prompt after installation
  5. On Windows, ensure "Add to PATH" was selected during installation

MySQL Connection Issues

Symptoms: "ECONNREFUSED", "Access denied", "Can't connect to MySQL server"
Solution: Check MySQL service and credentials
  1. Verify MySQL is running: sudo systemctl status mysql (Linux) or check Services (Windows)
  2. Check database credentials in .env file
  3. Test connection: mysql -u root -p
  4. Ensure database exists: CREATE DATABASE assettrack_db;
  5. Check firewall settings if using remote database

NPM Install Permission Errors

Symptoms: "EACCES: permission denied", "npm ERR! code EACCES"
Solution: Fix npm permissions or use alternative methods
  1. On Linux/macOS: sudo chown -R $(whoami) ~/.npm
  2. Or use nvm to manage Node.js versions
  3. On Windows, run Command Prompt as Administrator
  4. Clear npm cache: npm cache clean --force
  5. Delete node_modules and package-lock.json, then reinstall

Server Issues

Port Already in Use

Symptoms: "EADDRINUSE: address already in use :::3000"
Solution: Find and kill the process using the port
  1. Find process using port 3000: lsof -i :3000 (macOS/Linux) or netstat -ano | findstr :3000 (Windows)
  2. Kill the process: kill -9 PID (macOS/Linux) or taskkill /PID PID /F (Windows)
  3. Or change the port in .env file: PORT=3001
  4. Update client configuration to match new port

Database Migration Failures

Symptoms: "Migration failed", "Table already exists", "Sequelize errors"
Solution: Reset and recreate database
  1. Check database connection in .env file
  2. Reset database: npm run db:reset
  3. Or manually drop and recreate database
  4. Run migrations: npm run db:migrate
  5. Seed data: npm run db:seed

JWT Authentication Issues

Symptoms: "Invalid token", "jwt malformed", "Unauthorized"
Solution: Check JWT configuration and secret
  1. Verify JWT_SECRET in .env file is set and secure
  2. Ensure JWT_SECRET is at least 32 characters long
  3. Check JWT_EXPIRES_IN format (e.g., "24h", "7d")
  4. Clear browser cookies and local storage
  5. Restart server after changing JWT settings

Client Issues

Client Not Loading

Symptoms: Blank page, "Cannot GET /", build errors
Solution: Check build process and server configuration
  1. Verify client dependencies: npm install
  2. Check if server is running on correct port
  3. Update API configuration in src/config/config.ts
  4. Clear browser cache and hard refresh (Ctrl+F5)
  5. Check browser console for JavaScript errors

CORS Errors

Symptoms: "CORS policy", "Access-Control-Allow-Origin", "blocked by CORS"
Solution: Configure CORS settings in server
  1. Check ALLOWED_ORIGINS in server .env file
  2. Add client URL to allowed origins: http://localhost:5000
  3. Restart server after changing CORS settings
  4. For production, use HTTPS URLs
  5. Check if client and server are on different ports

File Upload Issues

Symptoms: "File too large", "Upload failed", "Permission denied"
Solution: Check file size limits and permissions
  1. Check MAX_FILE_SIZE in .env file (in bytes)
  2. Verify upload directory exists and is writable
  3. Check disk space on server
  4. Ensure file types are allowed
  5. Check server logs for detailed error messages

Performance Issues

Slow Application Performance

Symptoms: Slow page loads, timeouts, high memory usage
Solution: Optimize database and server configuration
  1. Check database query performance
  2. Add database indexes for frequently queried fields
  3. Increase server memory allocation
  4. Use PM2 for process management
  5. Enable database query caching
  6. Optimize images and static assets

Memory Leaks

Symptoms: Increasing memory usage, server crashes
Solution: Monitor and fix memory leaks
  1. Monitor memory usage: pm2 monit
  2. Check for unclosed database connections
  3. Review code for memory leaks in event listeners
  4. Set memory limits in PM2 configuration
  5. Restart server periodically if needed

Database Issues

Database Lock Issues

Symptoms: "Database is locked", "Deadlock found", "Lock wait timeout"
Solution: Optimize database queries and connections
  1. Check for long-running transactions
  2. Optimize database queries
  3. Increase lock timeout settings
  4. Use connection pooling
  5. Check for concurrent access issues

Connection Pool Exhaustion

Symptoms: "Too many connections", "Connection pool exhausted"
Solution: Configure connection pooling properly
  1. Increase max_connections in MySQL configuration
  2. Configure Sequelize connection pool settings
  3. Implement connection retry logic
  4. Monitor connection usage
  5. Close unused connections properly

Security Issues

SSL/HTTPS Issues

Symptoms: "Mixed content", "SSL certificate errors", "Not secure"
Solution: Configure SSL properly
  1. Obtain valid SSL certificate
  2. Configure web server (Nginx/Apache) for HTTPS
  3. Update ALLOWED_ORIGINS to use HTTPS
  4. Redirect HTTP to HTTPS
  5. Update client configuration for HTTPS

Authentication Bypass

Symptoms: Users accessing unauthorized resources, permission errors
Solution: Review and fix authentication logic
  1. Check JWT token validation
  2. Verify permission middleware
  3. Review user role assignments
  4. Test all protected routes
  5. Implement proper session management

Log Analysis

Server Logs

# View server logs tail -f /path/to/assets-manager/server/logs/combined.log # View error logs tail -f /path/to/assets-manager/server/logs/error.log # View PM2 logs pm2 logs assettrack-server # Filter specific errors grep "ERROR" /path/to/assets-manager/server/logs/combined.log

Database Logs

# MySQL error log sudo tail -f /var/log/mysql/error.log # MySQL slow query log sudo tail -f /var/log/mysql/slow.log # Check MySQL status sudo systemctl status mysql

System Logs

# System logs (Linux) sudo journalctl -u assettrack -f # Nginx logs sudo tail -f /var/log/nginx/error.log sudo tail -f /var/log/nginx/access.log # Apache logs sudo tail -f /var/log/apache2/error.log sudo tail -f /var/log/apache2/access.log

Getting Help

Before Seeking Help

  • Check this troubleshooting guide
  • Review server and client logs
  • Verify all configuration files
  • Test in a clean environment
  • Document the exact error messages

Information to Provide

  • Operating system and version
  • Node.js and npm versions
  • MySQL version
  • Exact error messages
  • Steps to reproduce the issue
  • Relevant log entries

Useful Commands

# System information node --version npm --version mysql --version uname -a # Process information ps aux | grep node ps aux | grep mysql # Network information netstat -tulpn | grep :3000 lsof -i :3000 # Disk space df -h du -sh /path/to/assets-manager # Memory usage free -h top