Cannot read properties of undefined (reading 'map'): the fix

TypeError: Cannot read properties of undefined (reading 'map') means you called .map() on a value that was undefined instead of an array. The array is missing, not the map method. It usually comes from data that has not loaded yet or from an API response with a different shape than you expected. The most common fix is to start the value as an empty array, [], and to read the array from the right property.

What does cannot read properties of undefined (reading ‘map’) mean?

Cannot read properties of undefined (reading 'map') means JavaScript looked up the map property on undefined. Only arrays have map, and undefined has no properties at all, so the lookup throws before map ever runs. Here the users sit under response.data, but the code reads response.users:

const response = { data: { users: [{ name: "Ava" }, { name: "Liam" }] } };
const names = response.users.map(user => user.name);
console.log(names);

TypeError: cannot read property 'map' of undefined
    at <eval> (main.js:2:29)

The JavaScript engine on this page words the message in an older style. Chrome, Edge and Node 22 print the same error as:

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

Both messages name the same bug. The value to the left of .map, here response.users, is the one to look at.

Why is the array undefined when I call map?

The undefined in front of .map comes from one of four places, most common first.

1. The data has not arrived yet

A page often renders before its fetch finishes. The variable that will hold the list is still undefined on the first render, so items.map(...) throws before the data ever lands. Our page has no network, so the snippet stands in for the fetch with a variable that is declared but not yet filled:

let products;

function renderList() {
  return products.map(product => product.title).join(", ");
}

console.log(renderList());

TypeError: cannot read property 'map' of undefined
    at renderList (main.js:4:18)
    at <eval> (main.js:7:23)

2. The response has a different shape

APIs rarely return a bare array. The list sits under data, results, items or users, as in the first snippet. Log the whole response once and read the array from the property it really uses.

3. A function that does not return the array

An arrow function with braces needs return. post => { post.tags } returns undefined, while post => post.tags returns the array:

const getTags = post => { post.tags };

const post = { title: "Hello", tags: ["js", "arrays"] };
console.log(getTags(post).map(tag => "#" + tag));

TypeError: cannot read property 'map' of undefined
    at <eval> (main.js:4:26)

4. A prop or argument that was never passed

A function or component that expects a list gets called without one. Inside it the parameter is undefined, and the first .map throws. In React that is a parent that forgot to pass the prop, or passed it under another name.

Why does React say cannot read properties of undefined (reading ‘map’)?

React shows Cannot read properties of undefined (reading 'map') when a component maps over state or a prop that is still undefined. The usual case is useState() with no starting value: the first render runs before the useEffect fetch finishes, so items.map runs on undefined. Start the state as an empty array:

const [items, setItems] = useState([]);

The first render then shows an empty list, and the real list appears when setItems runs. Our page runs plain JavaScript without a DOM, so the snippets here show the same mistake outside React.

Why do I get cannot read properties of null (reading ‘map’)?

Cannot read properties of null (reading 'map') is the same error with null in place of undefined. It comes from state started as useState(null), an API that sends null for an empty list, or JSON.parse of a saved value that was null:

const saved = JSON.parse("null");
console.log(saved.map(item => item.id));

TypeError: cannot read property 'map' of null
    at <eval> (main.js:2:18)

Chrome and Node 22 print it as:

TypeError: Cannot read properties of null (reading 'map')

How do I fix cannot read properties of undefined (reading ‘map’)?

Fix Cannot read properties of undefined (reading 'map') by making sure the value is an array before .map runs. Which fix fits depends on the cause.

Start the value as an empty array. Mapping over [] returns [], so nothing throws while you wait for the data:

let products = [];

function renderList() {
  return products.map(product => product.title).join(", ");
}

console.log("before:", renderList());
products = [{ title: "Lamp" }, { title: "Desk" }];
console.log("after:", renderList());

before: 
after: Lamp, Desk

Read the array from the property the response really uses, and return it from every function on the way:

const response = { data: { users: [{ name: "Ava" }, { name: "Liam" }] } };
const getUsers = res => res.data.users;
console.log(getUsers(response).map(user => user.name).join(", "));

Ava, Liam

Fall back to an empty array with ?? [] when the list may legitimately be missing. The ?? operator replaces both undefined and null, which a destructuring default does not: const { items = [] } = response still leaves items as null when the API sends null.

const responses = [{ items: [1, 2] }, { items: null }, {}];
for (const response of responses) {
  const { items = [] } = response;
  const safe = response.items ?? [];
  console.log(items === null ? "default kept null" : "default ok", safe.map(n => n * 10));
}

default ok [10,20]
default kept null []
default ok []

items?.map(...) also stops the error, but it gives undefined instead of an array, so the next .join or .length throws in turn. Prefer (items ?? []).map(...).

Check with Array.isArray when the value may be something other than an array. An object or a string passes a plain truthy check and then fails with items.map is not a function:

function titles(items) {
  if (!Array.isArray(items)) {
    return [];
  }
  return items.map(item => item.title);
}

console.log(titles([{ title: "Lamp" }]));
console.log(titles(undefined));
console.log(titles({ title: "Desk" }));

["Lamp"]
[]
[]

How do I find which value is undefined before map?

Find the missing array by logging the value just left of .map, and the object it came from. In response.data.users.map(...), the message only says map, so response.data.users is the undefined value and one of the links before it is wrong:

const response = { data: { results: [{ name: "Ava" }] } };
console.log(Object.keys(response.data));
console.log(response.data.users);

["results"]
undefined

The keys show the list is called results, not users. In the browser, the stack trace under the error gives the file and line of the .map call.

Can TypeScript catch it before the code runs?

TypeScript catches most of these once "strict": true is set in tsconfig.json. A variable typed Product[] | undefined, such as the state from useState<Product[]>() with no starting value, cannot call .map until you check it or give it a default. A response typed to its real shape also flags response.users when the property is data.users.

MDN covers Array.prototype.map, the nullish coalescing operator ?? and this family of TypeError messages. The general case, with any property name, is in TypeError: Cannot read properties of undefined.

Related errors

TypeError: items.map is not a function means the value exists but is not an array, usually an object or a string from an API; Array.isArray above is the guard for it. Cannot read properties of undefined (reading 'length') has the same causes on a missing array or string. Python’s version of a missing value is TypeError: ‘NoneType’ object is not subscriptable.