Node "ReferenceError: X is not defined" in CI - Track Down the Missing Symbol

ReferenceError means your code read an identifier that was never declared in scope. The crash point names the symbol Node could not find.

What this error means

A node process throws ReferenceError: <name> is not defined and exits non-zero. The name may be a variable, an import you forgot, or a browser-only global.

/home/runner/work/app/app/src/index.js:12
console.log(API_BASE);
            ^

ReferenceError: API_BASE is not defined
    at Object.<anonymous> (/home/runner/work/app/app/src/index.js:12:13)

Common causes

A missing import or require

The symbol is exported elsewhere but never imported into this file, so it is undeclared at runtime.

A browser-only global used under Node

Code assumes window, document, or localStorage, which do not exist in the Node CI runtime.

How to fix it

Import or declare the symbol

1. Find where the identifier is defined or exported.
2. Add the import, or declare the variable before use.
3. Re-run to confirm the reference resolves.

import { API_BASE } from './config.js';

Guard browser-only globals

1. Wrap browser globals in a typeof check so Node does not evaluate them.
2. Provide a Node fallback where one is needed.

const hasWindow = typeof window !== 'undefined';

How to prevent it

• Enable a no-undef lint rule, separate browser and Node entry points, and run the same code path locally that CI runs so missing references surface before merge.

Related guides