node Errors

110 error patterns

EADDRINUSE: Port already in use

Error: listen EADDRINUSE.*port

•Kill process using the port: lsof -i :PORT
•Use different port

ECONNREFUSED: Connection refused

Error: connect ECONNREFUSED

•Check target server is running
•Verify host and port are correct

ENOENT: No such file or directory

ENOENT.*no such file or directory

•Check file path is correct
•Use path.resolve for absolute paths

EACCES: Permission denied

EACCES.*permission denied

•Fix file permissions with chmod
•Don't run as root; fix ownership

ERR_MODULE_NOT_FOUND (ESM)

ERR_MODULE_NOT_FOUND

•Add .js extension to import paths in ESM
•Check package.json exports field

ERR_REQUIRE_ESM: require() of ES Module

ERR_REQUIRE_ESM

•Use dynamic import() instead of require()
•Convert project to ESM (type:module)

ERR_UNKNOWN_FILE_EXTENSION: .ts files

ERR_UNKNOWN_FILE_EXTENSION.*\.ts

•Use ts-node/esm loader or tsx
•Register TypeScript loader: --loader tsx

JWT: Invalid token or signature

JsonWebTokenError.*invalid (token|signature)

•Verify JWT secret matches between sign and verify
•Check token hasn't been tampered with

JWT: Token expired

TokenExpiredError.*jwt expired

•Implement refresh token flow
•Check server time synchronization

JWT: Token not yet active (nbf)

NotBeforeError.*jwt not active

•Check system clock synchronization
•Wait until nbf time passes

Express: 404 Cannot GET/POST route

(Express|app\.use).*404.*Cannot (GET|POST|PUT|DELETE)

•Check route path matches request
•Verify middleware/router order

Cannot set headers after they are sent

Error.*headers.*already.*sent

•Add return after res.send/json/redirect
•Don't call res.send twice

PayloadTooLargeError: Request entity too large

(body-parser|express\.json).*entity too large

•Increase limit: express.json({ limit: '50mb' })
•Use streaming for large files

CORS: Origin not allowed

CORS.*Origin.*not allowed|No 'Access-Control-Allow-Origin'

•Add cors middleware: app.use(cors())
•Configure allowed origins

CORS: Preflight OPTIONS request failing

CORS.*preflight.*405

•Handle OPTIONS method in route
•Add cors() middleware before routes

Multer: Unexpected field name

Multer.*Unexpected field

•Match field name in upload.single('fieldName') to form field
•Check multipart form data field names

Multer: File size exceeds limit

Multer.*File too large|LIMIT_FILE_SIZE

•Increase limits: { fileSize: 10 * 1024 * 1024 }
•Show user-friendly error message

Multer: Too many files uploaded

Multer.*LIMIT_UNEXPECTED_FILE

•Increase maxCount in upload.array()
•Limit file count on client side

Busboy: Missing content-type header

busboy.*missing content-type

•Ensure request has multipart/form-data content-type
•Check client sends correct headers

WebSocket: Connection reset

(WebSocket|ws).*ECONNRESET|connection.*reset

•Implement reconnection logic
•Handle close event and retry

WebSocket: Invalid frame header

(WebSocket|ws).*invalid frame header

•Check for proxy stripping upgrade headers
•Verify WebSocket protocol version

Socket.IO CORS blocked

socket\.io.*CORS.*blocked

•Configure cors in io options: { cors: { origin: '*' } }
•Add specific origin to Socket.IO cors

Socket.IO transport close/disconnect

socket\.io.*transport.*close|disconnect

•Increase pingTimeout and pingInterval
•Check client transport configuration

Worker thread out of memory

(Worker|worker_threads).*ERR_WORKER_OUT_OF_MEMORY

•Increase worker memory: resourceLimits.maxOldGenerationSizeMb
•Process data in smaller chunks

Worker: Cannot transfer MessagePort

(Worker|worker_threads).*Cannot.*transfer.*MessagePort

•Pass MessagePort in transferList array
•Don't use port after transferring

child_process spawn ENOENT

child_process.*ENOENT.*spawn

•Check command exists in PATH
•Use full path to executable

child_process: Operation not permitted

child_process.*EPERM|Operation not permitted

•Check file has execute permissions
•Run with appropriate user privileges

Crypto: Unsupported algorithm (OpenSSL)

(crypto|ERR_OSSL).*unsupported.*algorithm

•Use supported algorithm: sha256, aes-256-gcm
•Check Node.js version supports algorithm

Crypto: Invalid IV length

crypto.*ERR_CRYPTO_INVALID_IV_LENGTH

•Use correct IV length for algorithm (16 bytes for AES)
•Generate IV with crypto.randomBytes(16)

Crypto: Invalid key length

crypto.*ERR_CRYPTO_INVALID_KEY_LENGTH

•Use correct key length (32 bytes for AES-256)
•Derive key with scrypt/pbkdf2 to correct length

Buffer(): Deprecated Buffer constructor

(Buffer|DEP0005).*new Buffer.*deprecated

•Use Buffer.from() for strings/arrays
•Use Buffer.alloc() for new buffers

ERR_INVALID_ARG_TYPE: Expected string

ERR_INVALID_ARG_TYPE.*"(path|buffer)".*must be.*string

•Convert value to string before passing
•Check argument types match API requirements

Fetch/Undici: Connect timeout

(fetch|undici).*ConnectTimeoutError

•Increase timeout: signal: AbortSignal.timeout(30000)
•Check network connectivity

Fetch/Undici: Body timeout

(fetch|undici).*BodyTimeoutError

•Increase bodyTimeout in undici options
•Stream large responses instead

Fetch/Undici: Headers timeout

(fetch|undici).*HeadersTimeoutError

•Increase headersTimeout option
•Check server response time

AbortError: Operation was aborted

AbortError.*aborted|ERR_ABORTED

•Handle AbortError in catch block
•Increase timeout duration

AbortController: Signal already aborted

(AbortController|signal).*already.*aborted

•Create new AbortController for each request
•Don't reuse aborted controllers

HTTP/2 stream cancelled

ERR_HTTP2_STREAM_CANCEL

•Handle stream cancellation gracefully
•Implement retry logic

npm: No matching version found

ETARGET|No matching version found

•Check package name spelling
•Verify version exists: npm view package versions

npm: Unable to resolve dependency tree

ERESOLVE.*unable to resolve.*dependency tree

•Use --legacy-peer-deps flag
•Fix peer dependency conflicts

Rate limit exceeded (429)

rate.*limit.*exceeded|429.*Too Many Requests

•Implement exponential backoff
•Use rate limiting library (bottleneck, p-queue)

Fastify: Invalid content length

(Fastify|fastify).*FST_ERR_CTP_INVALID_CONTENT_LENGTH

•Set correct Content-Length header
•Use transfer-encoding: chunked

Fastify: Hook timeout

(Fastify|fastify).*FST_ERR_HOOK_TIMEOUT

•Increase hook timeout in plugin options
•Ensure hooks call done() or return promise

Fastify: Already decorated with this name

(Fastify|fastify).*already.*decorated

•Check for duplicate decorators
•Use hasDecorator() before decorating

Fastify: Schema validation failed

(Fastify|fastify).*schema.*validation.*failed

•Fix request body to match JSON schema
•Check required fields in schema

Hono: Route not found 404

(Hono|hono).*Not Found.*404

•Check route registration order
•Verify HTTP method matches

Hono: Middleware not calling next()

(Hono|hono).*middleware.*next.*not called

•Call await next() in middleware
•Return response or call next

EPIPE: Broken pipe

EPIPE.*Broken pipe

•Handle EPIPE error in stream error handler
•Client disconnected before response sent

ERR_HTTP_HEADERS_SENT

ERR_HTTP_HEADERS_SENT|Cannot.*headers.*already sent

•Return after sending response
•Don't send multiple responses

ERR_STREAM_WRITE_AFTER_END

ERR_STREAM_WRITE_AFTER_END

•Check stream.writable before writing
•Handle end event properly

ERR_STREAM_PREMATURE_CLOSE

ERR_STREAM_PREMATURE_CLOSE

•Handle stream close/error events
•Use pipeline() for proper error propagation

ERR_SOCKET_BAD_PORT: Port out of range

ERR_SOCKET_BAD_PORT|port.*should be.*0.*65535

•Use port number between 0 and 65535
•Parse port to integer: parseInt(process.env.PORT)

TLS: Certificate hostname mismatch

ERR_TLS_CERT_ALTNAME_INVALID

•Ensure certificate covers the hostname
•Use correct hostname matching SAN

TLS: Self-signed certificate error

UNABLE_TO_VERIFY_LEAF_SIGNATURE|SELF_SIGNED_CERT

•Add CA certificate to trusted: ca option
•Set NODE_TLS_REJECT_UNAUTHORIZED=0 for dev

TLS: Certificate authority invalid

ERR_CERT_AUTHORITY_INVALID

•Install proper root CA certificate
•Set NODE_EXTRA_CA_CERTS environment variable

ETIMEDOUT: Connection timed out

ETIMEDOUT|connect ETIMEDOUT

•Increase connection timeout
•Check network connectivity and DNS

ENOTFOUND: DNS lookup failed

ENOTFOUND|getaddrinfo.*ENOTFOUND

•Check hostname spelling
•Verify DNS resolution works

EMFILE: Too many open files

EMFILE.*too many open files

•Increase file descriptor limit: ulimit -n
•Use graceful-fs package

ERR_ASYNC_CALLBACK: Callback not a function

ERR_ASYNC_CALLBACK.*callback.*not.*function

•Pass function as callback argument
•Check callback parameter isn't undefined

Prisma P2002: Unique constraint violation

Prisma.*P2002.*Unique constraint failed

•Handle duplicate with upsert or try/catch
•Check unique fields before creating

Prisma P2025: Record not found

Prisma.*P2025.*Record.*not found

•Use findUnique with null check instead of findUniqueOrThrow
•Validate ID exists before update/delete

Prisma P2003: Foreign key constraint

Prisma.*P2003.*Foreign key constraint failed

•Ensure referenced record exists
•Check cascade delete settings

Prisma P1001: Cannot reach database

Prisma.*P1001.*Can't reach database server

•Check DATABASE_URL connection string
•Verify database server is running

Drizzle ORM: Column does not exist

Drizzle.*column.*does not exist

•Run migrations: drizzle-kit push
•Check schema matches database

Native crypto module build failed

(bcrypt|argon2).*ERR_DLOPEN_FAILED|native module

•Rebuild native modules: npm rebuild
•Install build tools (node-gyp prerequisites)

CSP: Resource blocked by Content-Security-Policy

(helmet|csp).*Content Security Policy.*blocked

•Add source to correct CSP directive
•Use nonce for inline scripts

Express session store disconnected

session.*store.*disconnect|connect\.session

•Check Redis/database connection for session store
•Handle store disconnect event

Passport: Failed to serialize user

(passport|authenticate).*Failed to serialize user

•Implement serializeUser: pass user.id to done()
•Check user object has id property

Passport: No strategy registered

(passport|authenticate).*No strategy.*registered

•Call passport.use(new Strategy()) before authenticate
•Check strategy name matches

HTTP/2 session destroyed/invalid

ERR_HTTP2_INVALID_SESSION|Session.*destroyed

•Create new session after close
•Handle session close event

Zod validation: Type mismatch

(zod|ZodError).*invalid_type.*Expected.*received

•Fix input data type to match schema
•Add coercion: z.coerce.number()

JavaScript heap out of memory

(ENOMEM|JavaScript heap out of memory)

•Increase memory: --max-old-space-size=4096
•Process data in streams/chunks

ERR_USE_AFTER_CLOSE: Resource used after close

ERR_USE_AFTER_CLOSE|use.*after.*close

•Check resource state before operations
•Don't reference connection after closing

ERR_UNESCAPED_CHARACTERS in URL

ERR_UNESCAPED_CHARACTERS.*in request path

•Use encodeURIComponent for URL parameters
•Sanitize URL path before request

Invalid cron expression

(cron|node-cron|agenda).*Invalid.*expression

•Verify cron syntax (5 or 6 fields)
•Use cron expression validator

Redis: Connection refused

(Redis|IORedis|redis).*ECONNREFUSED.*6379

•Ensure Redis server is running
•Check host/port configuration

Redis: Authentication required

(Redis|IORedis).*NOAUTH.*Authentication required

•Add password to Redis connection config
•Set AUTH in Redis URL: redis://:password@host

MongoDB: Connection refused

(mongoose|MongoDB).*ECONNREFUSED.*27017

•Ensure MongoDB is running
•Check connection string URI

Mongoose: Operation buffering timed out

(mongoose|MongoDB).*buffering timed out

•Ensure mongoose.connect() resolves before operations
•Check connection state

MongoDB: E11000 Duplicate key error

(mongoose|MongoDB).*E11000.*duplicate key

•Handle duplicate with try/catch
•Check unique index fields

ERR_INVALID_URL: Invalid URL

ERR_INVALID_URL|Invalid URL

•Validate URL format before parsing
•Use new URL() with try/catch

ERR_AMBIGUOUS_ARGUMENT in assert

ERR_AMBIGUOUS_ARGUMENT.*must not be.*falsy

•Pass truthy message to assert
•Don't pass empty string as message

DeprecationWarning: punycode module

DeprecationWarning.*punycode.*module

•Install userland punycode package
•Update packages using deprecated module

ExperimentalWarning: Fetch API

ExperimentalWarning.*Fetch API

•Update Node.js to 21+ where fetch is stable
•Add --no-warnings flag

Logger: Stream not writable

(pino|winston|bunyan).*stream.*not writable

•Check log file permissions
•Ensure log directory exists

Unhandled Promise Rejection

ERR_UNHANDLED_REJECTION.*No rejection handler

•Add .catch() to all promises
•Use process.on('unhandledRejection') handler

BullMQ: Missing lock for job

(bull|bullmq).*Missing.*lock.*job

•Increase lockDuration in worker options
•Don't process job longer than lock duration

BullMQ: Redis key type conflict

(bull|bullmq).*WRONGTYPE.*Operation against.*key.*different type

•Clear the queue: remove old keys
•Use different queue name

ERR_INSPECTOR_NOT_AVAILABLE

ERR_INSPECTOR_NOT_AVAILABLE

•Start Node.js with --inspect flag
•Don't use inspector in production

AWS SDK: No credentials found

(aws-sdk|@aws-sdk).*CredentialsError|No credentials

•Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
•Configure ~/.aws/credentials

AWS SDK: Network/Timeout error

(aws-sdk|@aws-sdk).*NetworkingError|TimeoutError

•Check VPC/security group allows outbound
•Increase maxRetries and timeout

Sharp: libvips/installation error

sharp.*libvips|Cannot find module 'sharp'

•Rebuild: npm rebuild sharp
•Install platform-specific binary: npm install --platform=linux

node-gyp: Build failed

node-gyp.*rebuild.*failed

•Install build tools: build-essential, python3
•On Windows: npm install -g windows-build-tools

ESBuild: Could not resolve module

(ESBuild|esbuild).*Could not resolve

•Add external for Node.js builtins
•Configure resolve extensions

Vite: Failed to resolve import

(Vite|vite).*Failed to resolve.*import

•Check import path and file exists
•Add to optimizeDeps.include

Vite: Pre-transform error

(Vite|vite).*Pre-transform error

•Clear Vite cache: rm -rf node_modules/.vite
•Check for circular imports

ERR_PACKAGE_PATH_NOT_EXPORTED

ERR_PACKAGE_PATH_NOT_EXPORTED

•Check package.json exports field of dependency
•Import from documented entry point

ERR_PACKAGE_IMPORT_NOT_DEFINED

ERR_PACKAGE_IMPORT_NOT_DEFINED

•Add imports field to package.json
•Check subpath import mapping

tsx/ts-node: Unknown file extension .ts

(tsx|ts-node).*ERR_UNKNOWN_FILE_EXTENSION

•Use tsx instead of ts-node for ESM
•Add --loader tsx to node command

Test runner: import in non-module

(vitest|jest).*Cannot.*use.*import.*outside.*module

•Add transform config for test runner
•Set type:module or configure babel/swc

Cannot use import/export outside a module

SyntaxError:.*Unexpected.*'export'|Cannot use import statement outside a module

•Add `"type": "module"` to package.json for ESM
•Rename file to .mjs for ESM or .cjs for CommonJS

Module not found

ERR_MODULE_NOT_FOUND|Cannot find (module|package)

•Run `npm install` to install missing dependencies
•Check the import path for typos and correct casing

Cannot require() an ES Module

ERR_REQUIRE_ESM|require\(\) of ES Module.*not supported

•Use dynamic `import()` instead of `require()`
•Downgrade to an older version of the package that supports CJS

ENOENT: File or directory not found

ENOENT:.*no such file or directory

•Check the file path for typos and ensure it exists
•Use path.resolve() or path.join() for cross-platform paths

EACCES: Permission denied

EACCES:.*permission denied

•Fix folder permissions: `chmod -R 755 <directory>` or take ownership on Windows
•Avoid running npm with sudo — fix npm prefix: `npm config set prefix ~/.npm-global`

EPERM: Operation not permitted

EPERM:.*operation not permitted

•Close applications that may have the file open (editors, dev servers)
•Run terminal as Administrator (Windows) or with sudo (Unix)

EADDRINUSE: Port already in use

EADDRINUSE:.*address already in use.*:\d+

•Kill the process using the port: `npx kill-port <port>` or `lsof -ti:<port> | xargs kill`
•Use a different port via environment variable or CLI flag

ENOSPC: Too many file watchers or no disk space

Error:.*ENOSPC|no space left on device|System limit for number of file watchers reached

•Increase file watcher limit: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`
•Free disk space — clear node_modules caches: `npm cache clean --force`

ENAMETOOLONG: File path too long

Error:.*ENAMETOOLONG|file name too long

•Shorten the file path or move the project closer to the root directory
•On Windows, enable long paths: `git config --system core.longpaths true`

JavaScript heap out of memory

heap out of memory|FATAL ERROR:.*allocation failed|JavaScript heap out of memory

•Increase Node.js memory: `node --max-old-space-size=8192`
•Set via env: `NODE_OPTIONS=--max-old-space-size=8192`