Skip to main content

Troubleshooting

Installation / creation issues​

npx: command not found​

Make sure you have Node.js and npm installed:

node --version   # should be >= 18.0.0
npm --version    # should be >= 8.0.0

Download from nodejs.org.

EEXIST: path already exists​

A folder with the same project name already exists at the chosen location.

Fix: Either delete the existing folder, choose a different name, or select "Ruta actual (.)" to scaffold into the current directory.

npm install fails during project creation​

This usually means you're offline or there's a registry issue.

Fix:

# Try with a different registry
npm install --registry https://registry.npmjs.org

# Or check your npm config
npm config get registry

husky: command not found during creation​

Husky needs Git to be initialized first. This is handled automatically — but if you see this error, Git may not be installed.

Fix: Install Git from git-scm.com and re-run.

Runtime issues​

Server doesn't start: Cannot find module './config/config-mongo'​

The config file for your chosen database is missing.

Fix: Check that the file exists:

ls src/config/
# should contain: config-mongo.js (or config-mysql.js, etc.)

MongooseError: The uri parameter to openUri() must be a string​

Your MONGO_URI environment variable is empty or .env was not loaded.

Fix:

  1. Check that .env exists in the project root
  2. Check that MONGO_URI has a value
  3. Make sure require('dotenv').config() is at the top of app.js

EADDRINUSE: address already in use :3000​

Port 3000 is already occupied.

Fix:

# macOS / Linux
lsof -ti:3000 | xargs kill

# Windows
netstat -ano | findstr :3000
taskkill /PID <pid> /F

Or change the port in .env:

PORT=3001

JsonWebTokenError: invalid signature​

The token was signed with a different JWT_SECRET.

Fix: Make sure JWT_SECRET in .env hasn't changed since the token was issued. Changing it invalidates all existing tokens — users must log in again.

Migration issues​

Sequelize has not been initialized​

The .sequelizerc file points to src/config/sequelize.js but the file wasn't generated or was deleted.

Fix: Check the file exists and has valid content:

cat src/config/sequelize.js

It should export a development, test, and production config object. Recreate it from the Generated Structure reference if needed.

npx sequelize-cli db:migrate — dialect not found​

The DB driver is missing.

Fix:

# MySQL
npm install mysql2

# PostgreSQL
npm install pg pg-hstore

SQL Server migration fails: Login failed​

The DB_USER or DB_PASSWORD in .env is incorrect, or SQL Server isn't running.

Fix:

  1. Confirm SQL Server is running (or docker compose up is active)
  2. Check credentials in .env match the database user
  3. Make sure the user has CREATE TABLE permissions on DB_NAME

Migration runs but tables are not created​

The migration file may have been applied but failed silently.

Fix: Check the SequelizeMeta table (MySQL/PostgreSQL) or _migrations table (SQL Server) to see which files were recorded. You can remove the entry and re-run:

-- MySQL / PostgreSQL
DELETE FROM "SequelizeMeta" WHERE name = '1234-create-product.js';

-- SQL Server
DELETE FROM _migrations WHERE filename = '1234-create-product.sql';

Then run npm run db:migrate again.

Docker issues​

docker compose up fails: port is already allocated​

Another process (your local DB) is already using the database port.

Fix: Stop your local database service before running Docker:

# macOS — Homebrew services
brew services stop mongodb-community
brew services stop mysql

# Or change the host port in docker-compose.yml
ports:
  - '27018:27017'   # map to a different host port

App container starts before database is ready​

The depends_on with condition: service_healthy should handle this — but it requires the DB image to support healthchecks.

Fix: If you're using a custom image, add a manual wait using wait-for-it or simply retry the migration after the stack is up:

docker compose up -d
sleep 10
docker compose exec app npm run db:migrate

npm run dev inside Docker doesn't hot-reload​

Volume mounts might not be working on Windows with WSL2.

Fix: In Docker Desktop, make sure your project folder is under the WSL2 filesystem (e.g., ~/projects/MyApp) rather than a Windows drive path (C:\Users\...).

TypeScript issues​

ts-node: command not found​

npm install --save-dev ts-node typescript

error TS2307: Cannot find module 'express'​

npm install --save-dev @types/express

All @types/* are installed automatically during creation. Add types manually for any new packages you install.

Type 'string | undefined' is not assignable to type 'string'​

Use a non-null assertion or a fallback:

const uri = process.env.MONGO_URI!;        // non-null assertion
// or
const uri = process.env.MONGO_URI ?? '';   // fallback
// or validate at startup:
if (!process.env.MONGO_URI) throw new Error('MONGO_URI is required');

Testing issues​

Jest: Cannot find module '../src/app'​

Make sure:

  1. src/app.js (or src/app.ts) exists
  2. The test file is in tests/ at the project root

Error: listen EADDRINUSE during tests​

app.js is calling app.listen() directly. It shouldn't — that's server.js's job.

Fix: app.js must end with module.exports = app and not call app.listen().

Tests fail because JWT_SECRET is undefined​

The test setup file (tests/setup.js) sets JWT_SECRET automatically via process.env. Make sure jest.config.js includes:

setupFiles: ['<rootDir>/tests/setup.js']

Coverage below 70% threshold​

Fix: Write tests for uncovered code, or temporarily lower the threshold in jest.config.js:

coverageThreshold: {
  global: { lines: 50, functions: 50, branches: 50 }
}

Getting help​

If your issue isn't listed here, open an issue on GitHub:

👉 github.com/FelipeV03/xpress-generator/issues

Please include:

  • Node.js and npm versions (node -v && npm -v)
  • The command you ran
  • The full error output