Node "Cannot read properties of undefined (reading X)" in CI - Fix the Null Access

By Daniel Zoghalchali·Latchkey

This TypeError means you read a property off undefined or null. The crash names the property, and the value one level up is the real culprit.

What this error means

A node process throws TypeError: Cannot read properties of undefined (reading "<prop>"). The object you indexed into was undefined at that point in CI.

TypeError: Cannot read properties of undefined (reading 'name')
    at formatUser (/home/runner/work/app/app/src/user.js:8:20)
    at Object.<anonymous> (/home/runner/work/app/app/src/index.js:3:1)

Common causes

An upstream lookup returned undefined

A find, parse, or API call returned no value in the CI data set, and the next line indexed into it.

A config or env value missing in CI

An object built from environment data is partial in CI, so a nested property is absent.

How to fix it

Guard with optional chaining and defaults

1. Use optional chaining so the access does not throw on undefined.
2. Provide a default for the missing branch.

const name = user?.name ?? 'unknown';

Assert the value exists before using it

1. Throw a descriptive error if the upstream value is missing.
2. That surfaces the real cause instead of an opaque property read.

if (!user) throw new Error('user not found for id ' + id);

How to prevent it

• Use TypeScript strict null checks and optional chaining, validate upstream lookups, and seed CI test data so objects are fully populated.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation