Node.js Server Not Starting— Complete Fix Guide 2026
⚡ Run These Checks First
# 1. Check for syntax errors (no execution)
node --check server.js
# 2. Install missing packages
npm install
# 3. Run with full error output
node --stack-trace-limit=100 server.jsThe error message will tell you exactly what is wrong. Still stuck? Every fix is below.
Diagnose in 60 Seconds — Read the Error
Node.js server not starting is always caused by one of eight specific problems. The error message in your terminal identifies which one. Match your error below and jump to the right fix:
Error Message → Cause → Fix
| Error contains... | Cause | Fix |
|---|---|---|
| SyntaxError: Unexpected token | Syntax error in your JS code | Jump → |
| Cannot find module | Missing npm package or wrong path | Jump → |
| EADDRINUSE: address already in use | Port is occupied by another process | Jump → |
| ENOENT: no such file | Wrong entry file name or path | Jump → |
| process.env.X is undefined | Missing .env file or dotenv not called | Jump → |
| node: command not found | Node.js not installed or not in PATH | Jump → |
| Starts then exits immediately | Unhandled error crashing the process | Jump → |
| No output at all | Silent failure — need verbose mode | Jump → |
Syntax Error in Your Code
SyntaxError: Unexpected tokenA syntax error prevents Node.js from even parsing your file. The error shows the exact file and line number.
SyntaxError: Unexpected token '}'
at wrapSafe (node:internal/modules/cjs/loader:1383:18)
at Module._compile (node:internal/modules/cjs/loader:1412:20)
at /Users/you/projects/app/server.js:42Check syntax without executing the file
node --check server.js
# Output example:
# /path/to/server.js:42
# const app = express()
# ^
# SyntaxError: Unexpected tokenCommon syntax mistakes
// Missing closing brace
app.get('/api', (req, res) => {
res.json({ data: 'hello' })
// ← missing }
// Missing comma in object
const config = {
host: 'localhost' // ← missing comma
port: 3000
}
// Unclosed string
const message = 'Hello world
// ← missing closing quote
// Wrong async/await
app.get('/api', async (req, res) => {
const data = fetchData() // ← missing await
})Use VS Code or any modern editor — it highlights syntax errors with red underlines in real time before you even run the file.
Missing npm Packages
Cannot find module 'express'# Install all packages from package.json
npm install
# If you just cloned a repo — always run this first
npm install
# Reinstall if node_modules is corrupted
rm -rf node_modules package-lock.json
npm installAfter any git clone, always run npm install before trying to start the server. node_modules is never committed to git.
Port Already in Use
EADDRINUSE: address already in use :::3000# macOS / Linux
kill -9 $(lsof -ti:3000)
# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
# Then restart
npm startSee the full article on Node.js port already in use for all scenarios.
Wrong Entry File Name or Path
ENOENT: no such file or directory# Check what files exist
ls *.js
# server.js? index.js? app.js?
# Check main field in package.json
cat package.json | grep main
# Run the correct file
node server.js
node index.js
node app.js
node src/index.jsCheck your package.json scripts section — the start script shows the exact file name: 'start': 'node server.js'. Make sure that file exists.
Missing Environment Variables
undefined env vars / .env not loadedrequire('dotenv').config() // must be FIRST line
const express = require('express')
// Now process.env.PORT, process.env.DATABASE_URL etc. are availableCheck .env file exists in project root
ls -la | grep .env
# Should show: .env
# If missing — create it
touch .env
# Then add your variables:
# PORT=3000
# DATABASE_URL=mongodb://localhost:27017/mydbDebug which variables are loaded
const result = require('dotenv').config()
console.log('dotenv loaded:', result.parsed)
console.log('PORT:', process.env.PORT)node Command Not Found
node: command not found# Install Node.js via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install --lts
nvm use --lts
# Verify
node --version
npm --versionApp Starts Then Immediately Stops
Process exits right after startingThe server starts but exits in under a second. This is an unhandled error crashing the process. The crash is silent unless you add error handlers.
Add crash catchers to see the real error
// Add these FIRST to catch all errors
process.on('uncaughtException', (err) => {
console.error('UNCAUGHT EXCEPTION:', err)
console.error(err.stack)
})
process.on('unhandledRejection', (reason, promise) => {
console.error('UNHANDLED REJECTION at:', promise)
console.error('Reason:', reason)
})Common causes of immediate crash
- Database connection failing at startup — app crashes before server starts listening
- Required environment variable is undefined and used immediately
- Importing a file that throws an error when loaded
- Calling an async function without awaiting at the top level
Wrap database connections in try/catch
async function startServer() {
try {
// Connect to database first
await mongoose.connect(process.env.MONGODB_URI)
console.log('Database connected')
// Only start server after DB is ready
app.listen(3000, () => {
console.log('Server running on port 3000')
})
} catch (err) {
console.error('Failed to start server:', err)
process.exit(1)
}
}
startServer()Run With Full Debug Output
No output — silent failureIf you see absolutely nothing — no error, no output — Node.js is failing silently. These commands extract the maximum possible detail:
# Maximum stack trace depth
node --stack-trace-limit=50 server.js
# Enable all debug logs
NODE_DEBUG=* node server.js
# Specific debug modules
NODE_DEBUG=net,http node server.js
# Use the Chrome debugger
node --inspect server.js
# Then open: chrome://inspect in Chrome browser
# Check Node.js version compatibility
node --versionHow to Prevent Node.js Not Starting
- Use VS Code or a linting editor — syntax errors are shown in real-time before you run
- Run node --check server.js before deploying or restarting
- Always run npm install after cloning a repo
- Add process.on('uncaughtException') and process.on('unhandledRejection') handlers
- Wrap database connections in try/catch with proper error logging
- Use nodemon in development for automatic restart with clear error output
- In production, use PM2 which captures crash logs and auto-restarts
- Keep a .env.example documenting required environment variables
Complete Diagnosis Checklist
- 1
Run node --check server.js
Finds syntax errors without executing
- 2
Run npm install
Fixes missing module errors
- 3
Kill the port: kill -9 $(lsof -ti:3000)
Fixes EADDRINUSE
- 4
Check file name: ls *.js
Ensures entry file exists
- 5
Check .env exists: ls -la | grep .env
Fixes missing env variables
- 6
Add uncaughtException handler
Reveals silent crash cause
- 7
Run node --stack-trace-limit=100 server.js
Maximum error detail
Frequently Asked Questions
Why is my Node.js server not starting?+−
Node.js app starts then immediately stops — why?+−
How do I debug a Node.js server that won't start?+−
Node.js server not starting after npm install?+−
How do I check if my Node.js syntax is correct?+−
Node.js starts locally but not on the server — why?+−
Need Expert Help?
We Build Production-Grade Node.js Apps
Softplix is a full-stack development agency. Dealing with complex Node.js startup issues in production? We can audit your app and fix it.
Talk to an Engineer