“Cannot read properties of undefined (reading '…')”

Updated 2026-08-27 · MateValidate

Uncaught TypeError: Cannot read properties of undefined (reading 'map')

If browsers had a most-played error, this is it — and AI-built apps produce it in industrial quantities, because generated code is systematically optimistic about data: it renders as if the fetch already succeeded, the list is never empty, and every field the model imagined actually exists.

Read the error like a sentence

Cannot read properties of undefined (reading 'map') says: the code did something.map(...), and something was undefined.

Two parts matter:

• The word in parentheses is what was being read — so the culprit is the expression to its left. For items.map, the question is "why is items undefined", never "what is wrong with map".
• The first stack line under the message names the file and line. Click it. In development it is your actual source; in production it may be minified — if so, reproduce locally where the names are readable, or paste the stack to your AI as-is.

Cannot read properties of null is the same failure with null in the role of undefined.

The three situations that produce it

1. The data has not arrived yet

The overwhelmingly common one in React apps. State starts as undefined, the component renders immediately, the fetch resolves later:

const [items, setItems] = useState();      // undefined on first render
useEffect(() => { fetchItems().then(setItems); }, []);
return <ul>{items.map(…)}</ul>;            // crashes before the fetch lands

Fix: make "not loaded yet" a state the component can render — initialize to an empty array (useState([])), or render a loading branch (if (!items) return <Spinner/>). This is a design fix, not a null-check sprinkled at the crash site.

2. The data arrived, but not in the expected shape

The code reads user.profile.avatarUrl; the API returns user.avatar_url, or profile is null for new users, or the response is { data: [...] } and the code treats the wrapper as the list. Generated code is especially prone to this: the model wrote plausible field names, and the real backend never had them.

Fix: log the actual response once (console.log(JSON.stringify(data))), compare it with what the code reads, and align the code with reality — not the other way around, unless you control the backend and the field is genuinely missing.

3. The data never arrived at all

If the Network tab shows the request red — CORS, 404, 401 — the undefined is just the echo of an upstream failure. Fix the request first: Failed to fetch and CORS for blocked requests, Supabase RLS for 401/403s that return empty data with the keys correctly set.

Why “just add ?.” makes it worse

Optional chaining (items?.map) stops the crash. It also converts the crash into silence: the list renders empty, forever, with no error anywhere. A crash tells you where it hurts; silence ships a page that quietly shows nothing and waits for a user to complain. Use ?. where absence is a real, designed state — and fix the actual reason the value is missing everywhere else. When you ask an AI to repair this error, say so explicitly, or sprinkled ?. is what you will get back.

Hand it to the AI

My app throws:

[paste the full error and the first stack lines]

The value being read is undefined. Find out WHY it is undefined — data not
loaded yet at first render, a mismatch between the API's real response shape
and what the code reads, or a failed request upstream — and fix that cause.
Do not fix it by adding optional chaining or try/catch at the crash site
unless undefined is a legitimate state there; if it is, render a proper
loading/empty state instead. Show me the actual response shape you found.

Prove it

Reload with the console open and walk the flow that crashed — including the cold path: a private window, a slow connection (DevTools → Network → throttling), and, if the app has accounts, a brand-new user with no data, which is the exact population for whom "the list is never empty" is false.