Cómo Solucionar el Error 'Cannot read properties of undefined (reading map)' en JavaScript

¿Qué significa el error 'Cannot read properties of undefined (reading map)'?

Este error se produce en JavaScript cuando intentas invocar el método Array.prototype.map() sobre una variable cuyo valor es undefined en lugar de ser una lista o array válido. Es especialmente frecuente en aplicaciones desarrolladas con frameworks como React, Vue o Angular al renderizar datos obtenidos de APIs asíncronas antes de que la respuesta haya sido recibida por completo.

Causas comunes del error

• Carga asíncrona de datos: El componente intenta renderizar la interfaz antes de que la petición HTTP (usando fetch o axios) haya resuelto y actualizado el estado.
• Estructura de respuesta incorrecta: La API devuelve un objeto que contiene el array dentro de una propiedad anidada (por ejemplo, data.results) y se intenta iterar directamente sobre el objeto principal.
• Estado inicial no definido: Inicializar variables de estado con undefined o sin ningún valor predeterminado en lugar de un array vacío ([]).

Método 1: Usar Optional Chaining (?.)

El encadenamiento opcional introducido en ECMAScript 2020 permite verificar si la variable existe antes de intentar acceder a sus métodos sin arrojar una excepción fatal.

1. Ubica la línea donde ejecutas la función .map() en tu código.
2. Agrega el operador de interrogación ?. justo antes del punto que invoca el método.

Ejemplo corregido:

const itemsList = data?.map(item => item.name);

Si data es undefined o null, la expresión simplemente devolverá undefined de forma silenciosa sin romper la ejecución de tu script.

Método 2: Inicializar con un array vacío y usar valores por defecto

Una de las mejores prácticas en el desarrollo frontend es asegurar que las variables destinadas a contener colecciones comiencen siempre como un array vacío.

1. En componentes de React, define el estado inicial pasando [] como argumento: const [usuarios, setUsuarios] = useState([]);.
2. Al recibir parámetros o props, utiliza el operador nullish coalescing (??) o el operador lógico OR (||) para garantizar un valor de respaldo:

const listaSegura = usuarios ?? [];
listaSegura.map(usuario => usuario.nombre);

Método 3: Renderizado condicional

Si dependes de que los datos estén disponibles antes de pintar elementos en el DOM, implementa una guarda de renderizado condicional.

1. Verifica explícitamente la existencia de la variable y valida que sea un array antes de llamar a map.
2. Muestra un indicador de carga mientras los datos se completan.

Ejemplo en React JSX:

{Array.isArray(productos) && productos.length > 0 ? ( productos.map(prod => <li key={prod.id}>{prod.titulo}</li>) ) : ( <p>Cargando información...</p> )}