EC
ERR_INVALID_ARG_VALUE
Node.jsERRORNotableAPI UsageHIGH confidence

An argument has a value that is out of the accepted range.

Production Risk

Medium. This may indicate a logical error in value calculation or a failure to handle edge cases, which could lead to unexpected behavior or crashes.

What this means

This error is thrown when the type of an argument is correct, but its value is outside the permissible range for a function or method. For instance, attempting to create a buffer with a negative size would trigger this. It indicates that the value, while of the right type, is semantically incorrect for the operation.

Why it happens
  1. 1A numeric value is negative when only positive values are allowed.
  2. 2A string value does not match a specific set of allowed values (e.g., an invalid encoding).
  3. 3A calculated value that is used as an argument results in an out-of-bounds number.
How to reproduce

This error occurs when a Node.js API validates the semantic value of an argument, after confirming its type is correct.

trigger — this will error
trigger — this will error
const os = require('os');
// Priority must be an integer between -20 and 19.
try {
  os.setPriority(os.constants.priority.PRIORITY_LOW, 100);
} catch (err) {
  console.error(err);
}

expected output

RangeError [ERR_INVALID_ARG_VALUE]: The argument 'priority' must be between -20 and 19. Received 100

Fix 1

Clamp or Validate Value

WHEN A value is passed to a function that has a specific numeric or string range.

Clamp or Validate Value
const os = require('os');
const myPriority = 10; // A value within the valid range
if (myPriority >= -20 && myPriority <= 19) {
  os.setPriority(myPriority);
} else {
  console.error('Priority is out of range.');
}

Why this works

Before calling a function, check the documentation for the accepted range of values for each argument. Add conditional logic to ensure your values are within the valid bounds.

Fix 2

Use Predefined Constants

WHEN An API provides constants for specific, valid values.

Use Predefined Constants
const crypto = require('crypto');
// Use a valid, supported encoding constant instead of a magic string.
const badEncoding = 'utf-9'; // Should be 'utf8'
crypto.createHash('sha256').update('some data', 'utf8');

Why this works

When an API exposes constants for arguments (e.g., encodings, flags), prefer using them over manually-typed strings to avoid typos and value errors.

Code examples
Triggerjs
const os = require('os');
// Priority must be an integer between -20 and 19.
try {
  os.setPriority(os.constants.priority.PRIORITY_LOW, 100);
} catch (err) {
  console.error(err);  // this triggers ERR_INVALID_ARG_VALUE
Handle in try/catchjs
try {
  // operation that may throw ERR_INVALID_ARG_VALUE
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_INVALID_ARG_VALUE') {
    console.error('ERR_INVALID_ARG_VALUE:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
const os = require('os')
const priority = Math.max(-20, Math.min(19, userValue))  // clamp to valid range
os.setPriority(priority)
What not to do

✕

✕

Sources
Official documentation ↗

https://github.com/nodejs/node/blob/main/lib/internal/errors.js

More information ↗

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Node.js errors