Node "ReferenceError: structuredClone is not defined" in CI

By Daniel Zoghalchali·Latchkey

The structuredClone global was added in Node 17. On Node 16 or earlier the function is undefined, so deep-cloning with it throws a ReferenceError on CI runners pinned to an older version.

What this error means

A structuredClone(obj) call fails with "ReferenceError: structuredClone is not defined" on an older Node runner while working locally.

node

const copy = structuredClone(state);
             ^

ReferenceError: structuredClone is not defined

Common causes

Runner uses Node older than 17

structuredClone is unavailable before Node 17, so the global reference fails.

A dependency relies on the global at run time

A library calls structuredClone expecting a modern runtime, surfacing the error from inside its code on old Node.

How to fix it

Upgrade the runner Node version

Pin Node 18+ so structuredClone is a built-in global.

.github/workflows/ci.yml

- uses: actions/setup-node@v4
  with:
    node-version: '20'

Polyfill structuredClone on legacy Node

If you cannot upgrade, install a polyfill and assign it to the global early in startup.

index.js

import structuredClone from '@ungap/structured-clone';
globalThis.structuredClone = structuredClone;

How to prevent it

Pin a modern Node version in CI.
Track the minimum Node your dependencies require.
Polyfill only as a last resort for legacy runtimes.

Frequently asked questions

What causes ""structuredClone is not defined""?

structuredClone is unavailable before Node 17, so the global reference fails.

How do I fix "structuredClone is not defined"?

Pin Node 18+ so structuredClone is a built-in global.