EC
ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT
Node.jsERRORCriticalNativeHIGH confidence

TypedArray buffer is not properly aligned for native addon

Production Risk

Low — only affects native addon code; follow TypedArray alignment rules.

What this means

Thrown when a native addon using Node-API attempts to create a TypedArray from an ArrayBuffer, but the buffers byte offset is not aligned to the element size of the TypedArray. For example, a Float64Array requires 8-byte alignment; an offset of 1 is invalid.

Why it happens
  1. 1Creating a TypedArray at a byte offset that is not a multiple of the element byte size
  2. 2Reinterpreting a byte buffer as a larger typed array without checking alignment
How to reproduce

Triggered from native C++ addon code when napi_create_typedarray() receives a misaligned offset.

trigger — this will error
trigger — this will error
// JavaScript equivalent of what the native code attempts:
const buffer = new ArrayBuffer(16);
// Float64Array requires 8-byte alignment; offset 1 is invalid:
new Float64Array(buffer, 1); // throws RangeError — same concept

expected output

Error [ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT]: Start offset of Float64Array should be a multiple of 8

Fix

Ensure TypedArray byte offsets are multiples of element size

WHEN When creating TypedArrays at specific offsets

Ensure TypedArray byte offsets are multiples of element size
const FLOAT64_SIZE = 8;
const offset = 16; // must be multiple of 8
const view = new Float64Array(buffer, offset);

Why this works

Aligning the offset to the element size satisfies both JS and native TypedArray requirements.

Code examples
Triggerjs
// JavaScript equivalent of what the native code attempts:
const buffer = new ArrayBuffer(16);
// Float64Array requires 8-byte alignment; offset 1 is invalid:
new Float64Array(buffer, 1); // throws RangeError — same concept  // this triggers ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT
Handle in try/catchjs
try {
  // operation that may throw ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT') {
    console.error('ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
// Validate inputs before calling the operation
function safe_err_napi_invalid_typedarray_alignment(...args) {
  // validate args here
  return performOperation(...args)
}
What not to do

✕ Create typed views at arbitrary byte offsets

TypedArrays require element-aligned offsets; misalignment causes immediate range errors.

Sources
Official documentation ↗

Node.js Error Codes Documentation

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

← All Node.js errors