阅读中文版本

Node ERR_INVALID_ARG_VALUE — Wrong Argument Type or Range

Trace ERR_INVALID_ARG_VALUE and ERR_INVALID_ARG_TYPE to the exact call site by reading the error code, syscall, and stack frame instead of guessing types.

node -e "try{ Buffer.alloc(-1) }catch(e){ console.log(e.code, e.message, e.stack.split('\n')[1]) }"

console.log({ type: typeof size, value: size, isNaN: Number.isNaN(size) })

Symptoms

When you hit “Node ERR_INVALID_ARG_VALUE — Wrong Argument Type or Range”, guessing wastes time. The guide below follows evidence: reproduce the symptom, run targeted diagnostics, identify the root cause, apply the fix, and verify it with concrete checks.

Observed symptoms include:

• Node throws “TypeError [ERR_INVALID_ARG_VALUE]: The argument … is invalid”
• The error stack points into Node internals rather than your code
• Works with a literal value but fails with a variable

Reproduce and Diagnose

Reproduce the failure in isolation before changing any code. Work through the checks below in order; each one narrows the search space.

Step 1: Read the full error object, not only the message

node -e "try{ Buffer.alloc(-1) }catch(e){ console.log(e.code, e.message, e.stack.split('\n')[1]) }"

The code and the first application stack frame tell you which argument is wrong and where it was supplied.

Step 2: Log the argument type and value at the call site

console.log({ type: typeof size, value: size, isNaN: Number.isNaN(size) })

A string “10” versus the number 10, or NaN from a failed parse, both trigger this error.

Likely contributors, in order of frequency:

• A value outside the permitted range is passed, such as a negative buffer size or an invalid encoding name
• The wrong type reaches a built-in API (a string where a number is required)
• A configuration or environment variable is empty, producing an undefined or invalid value

Root Cause

Node built-ins validate arguments with strict checks. A value of the wrong type or outside an allowed range fails fast with ERR_INVALID_ARG_TYPE or ERR_INVALID_ARG_VALUE before any work is done, which is why the stack leads into Node internals.

The Fix

Coerce and validate inputs at the boundary: parse numeric strings with Number() or parseInt and check Number.isFinite, assert the value is within range, and only then call the built-in API.

Watch out: Number() accepts “1e3” and “0x10”; when you need strict decimal input, validate the raw string before conversion.

function allocBuffer(raw) {
  const size = Number(raw);
  if (!Number.isInteger(size) || size < 0 || size > 1024) {
    throw new RangeError(`invalid buffer size: ${JSON.stringify(raw)}`);
  }
  return Buffer.alloc(size);
}

Verify and Prevent

Rerun the operation with valid inputs and confirm no error. Add unit tests covering undefined, empty string, and out-of-range values so the boundary validation is locked in.

Once verified, add a regression test that reproduces the original symptom so the failure cannot silently return.

This class of failure is usually environmental rather than pure logic, so capture the exact command, the environment variables, and the working directory in your bug report. Reproduce it in the smallest possible script, then widen the scope only once the minimal case is understood. A short written checklist for this failure mode saves hours the next time it appears.