skip to content

In Node.js, buf.subarray() returns a view rather than a copy; what production bugs does that cause, and when should you copy with Buffer.from()?

level: seniorimportance: should knowfreq 38%

answer

  1. same memory, different window
  2. slice on Buffer vs on Uint8Array
  3. a tiny view pins a big block
  4. buf.buffer and byteOffset
  5. copy before it outlives the call

basics

~20 s

buf.subarray() shares memory with buf, so later writes to the source show through and a small view keeps the whole underlying ArrayBuffer alive. Copy with Buffer.from(view) or Buffer.copyBytesFrom() whenever the bytes outlive the call or the source buffer is reused.

solid answer

~40 s

`buf.subarray(start, end)` returns a new `Buffer` over the **same memory**, so it costs nothing, but writes through either object show in both. `buf.slice()` does the same on a Buffer, unlike `Uint8Array.prototype.slice()`, which copies; Node has documentation-deprecated `buf.slice()` (DEP0158) in favour of `subarray()`. Three bugs follow: a reused source buffer silently rewrites payloads stored earlier as views; a 16-byte view kept in a cache pins the whole 64 KiB chunk it came from; and passing `buf.buffer` hands over the entire underlying `ArrayBuffer`, including bytes before `buf.byteOffset`. The rule: views inside the call, copies for anything that outlives it, using `Buffer.from(view)`, `Buffer.copyBytesFrom()` or `buf.copy()` into a buffer you own.

go deeper

for a junior

Recall that subarray shares memory with the original Buffer, so changing one changes the other.

for a middle

Explain the slice difference between Buffer and Uint8Array, why slice is deprecated in favour of subarray, and which calls copy and which share.

for a senior

Diagnose retained views from heap snapshots, explain how a reused scratch buffer corrupts stored payloads, and show when to copy with Buffer.from, copyBytesFrom or allocUnsafeSlow plus copy.

for a principal

Weigh zero-copy speed against retention and aliasing risk, and set a boundary rule: views inside a call, explicit copies for anything cached, queued or stored.

## Views, not copies `buf.subarray(start, end)` returns a new `Buffer` object that **references the same memory** as `buf`, offset and cropped by the two indexes. Nothing is copied, so it is constant-time regardless of size, which is why parsers use it to hand out fields and payloads. The price is **aliasing**: two objects, one block of memory. `buf.slice(start, end)` behaves the same way on a `Buffer`. That is the opposite of `Uint8Array.prototype.slice()`, which copies. Node kept the old behaviour for legacy compatibility and has documentation-deprecated `buf.slice()` since v17.5.0 and v16.15.0 (DEP0158) in favour of `subarray()`, whose behaviour is the same on every typed array. Code that moves between plain `Uint8Array` and `Buffer` is where this bites: the same `.slice()` call copies on one and aliases on the other. ## Bug 1: writes show through A write to the source changes every view, and a write through a view changes the source: ```js const a = Buffer.from('abc'); const b = a.subarray(0, 2); a[0] = 0x7a; // 'z' b.toString(); // 'zb' ``` In production this appears when a buffer is **reused**: - a fixed scratch buffer that each read fills, for example `fs.read()` into a buffer you pass in; - a parser that writes new bytes into the same pending buffer instead of allocating a new one; - a set of output buffers recycled after each response to save allocations. Payloads handed out earlier as views now show the new bytes. The symptoms are records that change after being stored, or several stored records that turn out identical. ## Bug 2: a small view pins a large block A view keeps its whole underlying `ArrayBuffer` alive. If a service keeps a 16-byte `subarray()` of each 64 KiB chunk in a long-lived `Map`, each entry retains 64 KiB, so memory grows about 4,000 times faster than the data the code believes it keeps. How it shows up: - `process.memoryUsage().arrayBuffers` climbs with traffic while the cache's logical size stays small; - a heap snapshot shows many large `ArrayBuffer`s whose only retainer is a tiny `Buffer`; - the growth stops as soon as the cached values are copied instead of kept as views. The shared allocation pool adds a variant. Small Buffers from `Buffer.allocUnsafe()`, `Buffer.from(string)`, `Buffer.from(array)` and `Buffer.concat()` can be carved from one pre-allocated slab of `Buffer.poolSize` bytes, so retaining one small pooled Buffer keeps the whole slab alive. For small chunks retained "for an indeterminate amount of time", Node's documentation suggests allocating an un-pooled Buffer with `Buffer.allocUnsafeSlow()` and copying the relevant bytes into it. ## Bug 3: `buf.buffer` is bigger than `buf` `buf.buffer` is the underlying `ArrayBuffer`, and Node does not guarantee it corresponds to `buf`. A view, or a small pooled Buffer, starts at `buf.byteOffset` inside a larger block. Code that passes `buf.buffer` on, to a typed-array constructor or a native addon, hands over the neighbouring bytes too, possibly another request's data, and reads from the wrong position. Pass the triple `buf.buffer, buf.byteOffset, buf.length`, or copy first. ## Choosing view or copy | Need | Use | Memory | |---|---|---| | Read a field during this call | `buf.subarray(s, e)` | shared | | Keep bytes after the source may change | `Buffer.from(buf.subarray(s, e))` | new copy | | Copy part of any typed array | `Buffer.copyBytesFrom(view, offset, length)` | new copy | | Copy into a buffer you already own | `src.copy(target, targetStart, s, e)` | into target | | Keep many small chunks long-term | `Buffer.allocUnsafeSlow(n)`, then `copy()` | un-pooled copy | | Wrap an existing `ArrayBuffer` | `Buffer.from(arrayBuffer, byteOffset, length)` | shared | `Buffer.from()` has two personalities: given a `Buffer` or an array it **copies**; given an `ArrayBuffer` it **shares**. ## A rule a team can apply 1. Views are fine inside the function that received the bytes. 2. Anything that outlives the call, stored in a cache, a map, a queue or a closure, is copied first. 3. Code that reuses a buffer says so in a comment, because every view of it becomes a hazard. 4. Memory growth that tracks traffic, with `ArrayBuffer`s retained by small `Buffer`s, is checked for retained views before anything else. The defaults point the right way: `subarray()` for speed inside a call, an explicit copy at the boundary where data starts living longer than the bytes it came from.

  • Does copying with Buffer.from(view) fully stop small retained chunks from pinning memory?
    It stops the copy from pinning the original chunk, but in Node 24 a small `Buffer.from(buffer)` copy is itself carved from the shared allocation pool, so a long-lived copy keeps a whole pool slab of `Buffer.poolSize` bytes alive along with its neighbours. For many small, long-lived chunks, Node's documentation suggests `Buffer.allocUnsafeSlow(n)` plus `copy()`, which gives each chunk its own un-pooled memory.
  • Why does Node keep buf.slice() returning a view instead of making it copy like Uint8Array?
    Existing code relies on `buf.slice()` returning a view, writing through it or depending on it being free, so Node keeps that behaviour for legacy compatibility. Since v17.5.0 and v16.15.0 it is documentation-deprecated (DEP0158) in favour of `subarray()`, which aliases on every typed array, while `Uint8Array.prototype.slice()` remains the copying spelling.

A subarray is a window cut in a mask laid over a printed sheet, not a photocopy: anything later printed on the sheet shows through the window, and the whole sheet has to stay on the desk for as long as anyone is still looking through it.

  • buf.subarray() and buf.slice() both return independent copies
  • Buffer.from(arrayBuffer) copies the bytes just like Buffer.from(buffer)
  • A small view only keeps its own bytes alive; the rest is garbage-collected
  • buf.buffer always holds exactly the bytes of buf, starting at offset 0
  • Calling buf.slice() on a Buffer copies, as it does on a Uint8Array