Fix "Next.js Port 3000 Error" Issues

Can't start your Next.js development server on port 3000? Getting "port already in use", EADDRINUSE, or Fast Refresh issues? This complete guide covers all Next.js port 3000 troubleshooting for Next.js 13, 14, and 15.

Next.js 15 Next.js 14 Next.js 13 App Router Pages Router

Common Next.js Port 3000 Errors

Port Already in Use Error: 
Error: listen EADDRINUSE: address already in use :::3000
    at Server.setupListenHandle [as _listen2] (net.js:1318:16)

Port 3000 is already in use. Try using a different port.

Error occurred while starting the server:
Error: listen EADDRINUSE :::3000
Next.js Startup Failed: 
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
Error: Something is already running on port 3000.

Failed to start server
Error: Port 3000 is already in use
Fast Refresh Not Working: 
Fast Refresh had to perform a full reload.
Read more: https://nextjs.org/docs/messages/fast-refresh-reload

[Fast Refresh] rebuilding

Fast Refresh had to perform a full reload due to a runtime error.
Connection Refused in Browser: 
This site can't be reached
localhost refused to connect.

ERR_CONNECTION_REFUSED

Try:
• Checking the connection
• Checking the proxy and the firewall

Quick Fix (Choose Your Operating System)

The Problem: Another process is using port 3000

  1. Find process: netstat -ano | findstr :3000
  2. Kill process: taskkill /PID [PID] /F
  3. Or use different port: npm run dev -- -p 3001
  4. Test: Open http://localhost:3001
  1. Find process: lsof -i :3000
  2. Kill process: kill -9 [PID]
  3. Or quick kill: npx kill-port 3000
  4. Or use different port: npm run dev -- -p 3001
  1. Find process: lsof -i :3000
  2. Kill process: kill -9 [PID]
  3. Or kill all on port: lsof -ti:3000 | xargs kill -9
  4. Or use different port: npm run dev -- -p 3001

Complete Troubleshooting Guide

1 Change Next.js Development Server Port

Method 1: Command Line Flag (Temporary)

bash 
# npm
npm run dev -- -p 3001

# yarn
yarn dev -p 3001

# pnpm
pnpm dev -p 3001

Method 2: Modify package.json Scripts (Persistent)

json 
{
  "scripts": {
    "dev": "next dev -p 3001",
    "dev:3000": "next dev -p 3000",
    "dev:3002": "next dev -p 3002",
    "build": "next build",
    "start": "next start -p 3001"
  }
}

Method 3: Environment Variable (.env.local)

bash 
# Create .env.local in project root
PORT=3001

# Then run normally
npm run dev

Method 4: next.config.js (Next.js 13+)

javascript 
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Note: This doesn't directly set port in newer versions
  // Use package.json scripts or -p flag instead
}

module.exports = nextConfig
Port Priority: Command line flag -p takes highest priority, followed by PORT environment variable, then package.json scripts.

2 Kill Process Using Port 3000

cmd 
# Find process using port 3000
netstat -ano | findstr :3000

# Output example:
# TCP    0.0.0.0:3000      0.0.0.0:0      LISTENING       12345
# The last number (12345) is the PID

# Kill the process
taskkill /PID 12345 /F

# Or kill all Node.js processes (use with caution!)
taskkill /IM node.exe /F
bash 
# Find process using port 3000
lsof -i :3000

# Kill the process (replace PID)
kill -9 12345

# Or kill all processes on port 3000
lsof -ti:3000 | xargs kill -9

# Using npx kill-port (easiest)
npx kill-port 3000
bash 
# Find process using port 3000
lsof -i :3000
# or
netstat -tulpn | grep :3000

# Kill the process
kill -9 12345

# Or kill all on port 3000
lsof -ti:3000 | xargs kill -9

# Using fuser
fuser -k 3000/tcp

3 Fix Fast Refresh Issues

If Fast Refresh is not working or causing full page reloads:

Clear Next.js Cache:

bash 
# Delete .next cache folder
rm -rf .next

# Windows
rmdir /s .next

# Also clear node_modules cache
rm -rf node_modules/.cache

# Restart dev server
npm run dev

Enable Polling for WSL/Docker/VMs:

javascript 
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Enable webpack polling for file watching in WSL/Docker
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.watchOptions = {
        poll: 1000, // Check for changes every second
        aggregateTimeout: 300,
      }
    }
    return config
  },
}

module.exports = nextConfig

Check for Syntax Errors:

javascript 
// Fast Refresh requires valid React component syntax

// ❌ This breaks Fast Refresh (anonymous export)
export default () => 
Hello


// ✓ This works (named function)
export default function HomePage() {
  return 
Hello

}

// ❌ Class component with anonymous export
export default class extends React.Component {}

// ✓ Class component with name
export default class HomePage extends React.Component {}
Fast Refresh Requirements: Components must be in pages/ or app/ directory, have named exports or default exports with function names, and contain no syntax errors.

4 Fix Connection Refused Errors

If dev server starts but browser shows "connection refused":

Try Different Localhost Formats:

text 
# Try these URLs in order:
http://localhost:3000
http://127.0.0.1:3000
http://0.0.0.0:3000

# For WSL users, get your WSL IP:
hostname -I
# Then use: http://[WSL-IP]:3000

Check Firewall Settings:

bash 
# Windows - Allow Node.js through firewall
# Control Panel → Windows Defender Firewall → Allow an app

# macOS - Check firewall
# System Preferences → Security & Privacy → Firewall

# Linux - Allow port 3000
sudo ufw allow 3000/tcp

# Test if port is accessible
curl http://localhost:3000
# or
telnet localhost 3000

For WSL (Windows Subsystem for Linux):

bash 
# In WSL, start Next.js bound to all interfaces
npm run dev -- -H 0.0.0.0

# Get your WSL IP address
ip addr show eth0 | grep "inet\b" | awk '{print $2}' | cut -d/ -f1

# Access from Windows browser using WSL IP
# Example: http://172.18.xxx.xxx:3000

# Or add to package.json
"scripts": {
  "dev": "next dev -H 0.0.0.0"
}

5 Fix Module and Dependency Issues

Cannot Find Module Errors:

bash 
# Clear and reinstall dependencies
rm -rf node_modules package-lock.json .next
npm install

# Or with yarn
rm -rf node_modules yarn.lock .next
yarn install

# Or with pnpm
rm -rf node_modules pnpm-lock.yaml .next
pnpm install

Version Conflicts:

bash 
# Check Next.js version
npm list next

# Update Next.js to latest
npm install next@latest react@latest react-dom@latest

# Or specific version
npm install [email protected] react@18 react-dom@18

# Check for peer dependency warnings
npm install 2>&1 | grep WARN

TypeScript Configuration Issues:

bash 
# Next.js auto-generates tsconfig.json
# If it's corrupted, delete and restart dev server
rm tsconfig.json
npm run dev  # Will regenerate automatically

# Install TypeScript types if missing
npm install --save-dev @types/react @types/node

6 Debug with Detailed Logging

Enable Next.js Debug Mode:

bash 
# Show detailed build output
npm run dev -- --debug

# Or set NODE_OPTIONS
NODE_OPTIONS='--inspect' npm run dev

# Check Next.js version and config
npx next info

# Output example:
# Operating System: Platform: darwin, Arch: arm64, Version: Darwin Kernel
# Binaries: Node: 18.17.0, npm: 9.6.7, Yarn: N/A, pnpm: N/A
# Relevant packages: next: 14.0.0, react: 18.2.0, react-dom: 18.2.0

Check Build Errors:

bash 
# Try building to see compilation errors
npm run build

# This will show all errors that might be hidden in dev mode
# Look for:
# - TypeScript errors
# - ESLint errors
# - Import/export errors
# - Missing dependencies

7 Docker and Container Issues

Next.js in Docker Compose:

yaml 
# docker-compose.yml
version: '3.8'
services:
  nextjs:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    command: npm run dev

Dockerfile for Next.js:

dockerfile 
# Dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 3000

# For development with hot reload
CMD ["npm", "run", "dev"]

# For production
# RUN npm run build
# CMD ["npm", "start"]

Fix Hot Reload in Docker:

javascript 
// next.config.js for Docker
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Use polling for file watching in Docker
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.watchOptions = {
        poll: 1000,
        aggregateTimeout: 300,
      }
    }
    return config
  },
}

module.exports = nextConfig

Common Scenarios and Solutions

Scenario 1: Multiple Next.js Projects Running

Problem: You have several Next.js projects and they conflict on port 3000

Solution:

bash 
# Assign different ports to each project in package.json

# Project 1: package.json
"scripts": {
  "dev": "next dev -p 3000"
}

# Project 2: package.json
"scripts": {
  "dev": "next dev -p 3001"
}

# Project 3: package.json
"scripts": {
  "dev": "next dev -p 3002"
}

# Or use environment-based ports
"scripts": {
  "dev": "next dev -p ${PORT:-3000}"
}

Scenario 2: Next.js App Router vs Pages Router

Both App Router and Pages Router use the same port configuration methods.

text 
App Router Structure (Next.js 13+):
  app/
    layout.tsx
    page.tsx

Pages Router Structure (Next.js 12 and earlier):
  pages/
    _app.tsx
    index.tsx

Both use: npm run dev -- -p 3001

Scenario 3: Turbopack Issues (Next.js 14+)

If using Turbopack and experiencing issues:

bash 
# Try without Turbopack
npm run dev

# Or explicitly disable
npm run dev -- --no-turbo

# If package.json has:
"scripts": {
  "dev": "next dev --turbo"
}

# Change to:
"scripts": {
  "dev": "next dev"
}

Related Troubleshooting Guides

Port 3000 Complete Guide Everything about port 3000 for developers React Port 3000 Issues Fix React development server port problems npm EADDRINUSE Fix Resolve npm port already in use errors Port Already in Use Guide Universal port conflict solutions ERR_CONNECTION_REFUSED Fix Fix connection refused errors on localhost:3000 Developer Tools Port checker and diagnostic tools

Quick Reference Commands

cheatsheet 
NEXT.JS PORT TROUBLESHOOTING CHEATSHEET
========================================

Change Next.js port:
  npm:      npm run dev -- -p 3001
  yarn:     yarn dev -p 3001
  pnpm:     pnpm dev -p 3001

Find what's using port 3000:
  macOS:    lsof -i :3000
  Linux:    lsof -i :3000
  Windows:  netstat -ano | findstr :3000

Kill process on port:
  macOS:    kill -9 [PID]
  Linux:    kill -9 [PID]
  Windows:  taskkill /PID [PID] /F
  Universal: npx kill-port 3000

Clear Next.js cache:
  rm -rf .next node_modules/.cache

Full clean reinstall:
  rm -rf node_modules .next package-lock.json
  npm install
  npm run dev

Check Next.js info:
  npx next info

Enable debug mode:
  npm run dev -- --debug

WSL users:
  npm run dev -- -H 0.0.0.0
  Access via WSL IP address

Docker users:
  Add polling to next.config.js
  Ensure port 3000 is exposed

Still Having Issues?

Debugging checklist:

Visit our Interactive Diagnostic Wizard for personalized help.

Back to Locallhost.dev Home