Troubleshooting

Common issues and fixes for Salon Management (Node server, MySQL, browser)

Table of contents

Installation

Node.js not found

Symptoms: node --version fails with “command not found”.

What to try:

  1. Install current LTS from nodejs.org or use your OS package manager (see Linux / macOS guides).
  2. Restart the terminal after installing.
  3. On Windows, confirm PATH includes Node or sign out and back in.

npm not found

Symptoms: npm is missing while node works.

What to try: Reinstall Node (npm ships with it). If you use a version manager (nvm, fnm), ensure the shell loads the right profile (.zshrc, .bashrc).

MySQL not running

Symptoms: ECONNREFUSED, connection errors, or timeouts to port 3306.

What to try:

  1. Windows: Services → MySQL → Start.
  2. Linux: sudo systemctl status mysql (or mysqld) and start the service.
  3. macOS: brew services list and brew services start mysql if you installed via Homebrew.

Database connection

“Access denied for user”

Symptoms: MySQL rejects the user in server/.env.

What to try:

  1. Confirm DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, and DB_NAME (this project uses DB_USER, not DB_USERNAME).
  2. Test manually: mysql -h 127.0.0.1 -P 3306 -u your_user -p
  3. Ensure the user is granted ALL PRIVILEGES on the application database only, for production.

“Unknown database”

Symptoms: Error mentions an unknown database (e.g. salon_management).

What to try:

  1. Create it: CREATE DATABASE salon_management CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  2. Or change DB_NAME in .env to match a database you already created.

“Can’t connect to MySQL server”

What to try: Confirm MySQL is running; DB_HOST is 127.0.0.1 or localhost for local installs; firewall allows the port if the DB is remote.

Checklist

No trailing spaces in .env values. Run Sequelize CLI commands from the server directory so .sequelizerc and dotenv resolve correctly.

Migrations

npm run db:migrate fails

What to try:

  1. Database exists and credentials work (see above).
  2. User can CREATE/ALTER tables.
  3. From server, check status: 
    npx sequelize-cli db:migrate:status
  4. Read the error text — duplicate column/table names often mean a partial migration run.

“Table already exists”

What to try: On a throwaway dev database you can drop and recreate the schema, or undo migrations carefully:

npm run db:migrate:undo
# or, to undo all (destructive):
npm run db:migrate:undo:all

Do not drop production databases without backups.

SequelizeConnectionError during migrate

What to try: Fix DB connectivity first. Confirm NODE_ENV matches the Sequelize environment you expect (CLI typically uses development unless you set NODE_ENV).

Seeders

npm run db:seed fails

What to try:

  1. Run npm run db:migrate successfully first.
  2. Check SHOW TABLES; in MySQL — required tables must exist.
  3. If seeders were partially applied, you may need npm run db:seed:undo (see package scripts) before re-seeding in development only.

Foreign key errors during seeding

What to try: Seeders run in filename order under server/seeders/. Ensure earlier seeders create parent rows. For a clean dev DB, migrate then seed from scratch.

Demo accounts

After a successful seed, use the demo emails with password Admin@1234 (see Home). If login fails, confirm seeders ran and the user exists in MySQL. Reference comments in server/.env-example for JWT variables.

Browser, EJS & uploads

404 on a page you expect to exist

What to try: URLs match Express routes (for example /auth/login, /dashboard). The home route redirects to login. Check the server log for the requested path.

401 / “Unauthorized” or redirect to login

What to try: Confirm JWT_SECRET is set in server/.env, seeders ran, and credentials are correct. If you changed JWT_SECRET, old tokens are invalid — sign in again. Ensure the browser sends the auth mechanism your app expects (stored token / cookie per your build).

JSON error responses in the browser

Some routes return JSON when Accept: application/json is preferred. For normal navigation, load HTML pages from the same origin as the app.

Images or files under /uploads return 404

What to try: Files live under server/public/uploads (for example profile, salon-logo). Ensure Express static middleware can read them, the file exists on disk, and your reverse proxy forwards /uploads to Node in production (see Server Configuration).

Logo or profile upload fails

What to try: Check write permissions on server/public/uploads and subfolders. If Multer reports file size errors, reduce image size or adjust the configured limit in the upload middleware.

Wrong language or missing translations

What to try: i18next uses supported locales in the app config. Use the language switcher or ?lng= query parameter if your deployment supports it; clear cookies if a stale locale is stored.

Server startup

“Cannot find module”

What to try: From server, run npm install. If problems persist, remove node_modules and reinstall.

Port already in use (EADDRINUSE)

What to try: Change PORT in .env or stop the other process (see Port conflicts).

JWT / environment errors

What to try: Ensure JWT_SECRET is present in server/.env for production; development may fall back to a default (still set a real secret before go-live). Restart npm run dev or PM2 after edits.

Demo seed cron

Data keeps resetting

Symptoms: Users, appointments, or invoices disappear every few hours.

What to try: If DEMO_SEED_CRON_ENABLED=true in server/.env, the server periodically truncates tables and re-runs seeders. Set it to false or remove it for any environment where you need persistent data.

Production

Never enable the demo re-seed cron on a production database.

Port conflicts

Windows

netstat -ano | findstr :3000

Stop the process: taskkill /PID <pid> /F

Linux / macOS

lsof -i :3000

Stop with kill <pid> or change PORT in server/.env.

Tip

The app listens on PORT (default 3000). There is no separate Vite dev server in this repository.

Permissions

Windows

Run the terminal elevated only if the install truly requires it; avoid unnecessary Administrator npm installs.

Linux / macOS

Avoid sudo npm install in the project folder (can break ownership). Fix ownership with chown if needed. Ensure the user running Node can write to server/public/uploads and subfolders used for Multer.

Database user lacks rights

GRANT ALL PRIVILEGES ON salon_management.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;

Dependencies

npm install errors

What to try: Clear cache, reinstall, update npm:

npm cache clean --force
rm -rf node_modules package-lock.json   # macOS/Linux; on Windows delete folders in Explorer or PowerShell
npm install

Node version

Salon Management targets modern Node (18+ recommended). Check node --version.

Native addons

This project uses bcryptjs (pure JS). mysql2 may need build tools on unusual setups — install Python / build tools per Node’s docs for your OS.

Verification steps

1. Tooling

node --version
npm --version
mysql --version

2. Database

mysql -u your_user -p -e "SHOW DATABASES LIKE 'salon_management';"

3. Environment

server/.env should define at least: DB_NAME, DB_USER, DB_PASSWORD (if used), DB_HOST, JWT_SECRET, PORT. Copy from server/.env-example as a starting point.

4. Server

cd server
npm install
npm run db:migrate
npm run db:seed
npm run dev

Expect the app on http://127.0.0.1:3000 (or your PORT). Open /auth/login in a browser.

Working setup

You should reach the sign-in page, authenticate with a seeded account, and load the dashboard without repeated database errors in the server terminal.

Still need help?

  • Capture the exact error message and stack trace from the server terminal and the browser console.
  • Confirm server/.env and restart the server after changes.
  • Review Home, Server Configuration, and your OS guide (Linux, macOS, Windows).