# "Cannot read properties of undefined": l'errore JavaScript più comune, spiegato

> Perché compare 'TypeError: Cannot read properties of undefined (reading ...)', le tre cause più comuni, e come optional chaining e nullish coalescing lo prevengono.

- Autore / Author: Diego Betto (https://diegobetto.com/about/)
- Pubblicato / Published: 2026-09-16
- URL: https://diegobetto.com/javascript-cannot-read-properties-of-undefined/
- Tag: javascript, errori, typeerror, optional chaining

Se scrivi JavaScript da più di una settimana, l'hai già visto:

> **Errore**
>
> TypeError: Cannot read properties of undefined (reading 'name')

È probabilmente l'errore JavaScript più cercato su internet, e con buoni motivi: capita in continuazione, in codice che altrimenti sembra perfettamente corretto. Ecco cosa significa esattamente e le poche forme in cui si presenta quasi sempre.

## Cosa significa davvero

Il messaggio è letterale: il tuo codice ha provato ad accedere a una proprietà (`.name` nell'esempio sopra) su un valore che è `undefined`. `undefined` non ha proprietà, quindi JavaScript lancia un errore invece di restituire silenziosamente qualcosa di inutile.

```js
const user = undefined;
console.log(user.name); // TypeError: Cannot read properties of undefined (reading 'name')
```

La parte tra parentesi — `(reading 'name')` — è il pezzo più utile di tutto il messaggio: ti dice esattamente quale accesso a proprietà è fallito, il che restringe la ricerca anche in una catena lunga come `a.b.c.d`.

## Causa #1: dati non ancora caricati

Di gran lunga il caso più comune nelle app reali: renderizzi un componente (o esegui codice) prima che un'operazione asincrona si sia risolta.

```js
function UserCard({ user }) {
  // user è undefined al primo render, prima che la fetch si risolva
  return <p>{user.name}</p>;
}
```

```js
const [user, setUser] = useState();

useEffect(() => {
  fetchUser().then(setUser);
}, []);

// Al primissimo render, `user` qui è ancora undefined
```

La correzione è gestire esplicitamente lo stato "non ancora caricato", invece di assumere che i dati ci siano sempre:

```js
function UserCard({ user }) {
  if (!user) return <p>Caricamento...</p>;
  return <p>{user.name}</p>;
}
```

## Causa #2: destrutturare un valore che potrebbe essere null

```js
function getCity({ address }) {
  return address.city; // lancia se address è null/undefined
}

getCity({ name: "Acme Corp" }); // nessuna chiave `address`
```

Capita spesso con risposte di API dove un campo è opzionale e il backend semplicemente lo omette invece di inviare `null` — quindi `response.address` è `undefined`, e `.city` su di esso lancia l'errore.

## Causa #3: accedere a un elemento di un array vuoto

```js
const results = [];
console.log(results[0].id); // results[0] è undefined, non un oggetto
```

Gli array non lanciano errori quando accedi fuori dai limiti — ottieni semplicemente `undefined` — ma l'accesso _successivo_ a una proprietà di quell'`undefined` sì. Questo caso confonde perché l'array stesso sembra perfettamente valido.

## La correzione: optional chaining e nullish coalescing

Il JavaScript moderno offre due operatori costruiti apposta per questo:

```js
// Optional chaining: si ferma a undefined invece di lanciare un errore
const city = address?.city;
const firstResultId = results[0]?.id;
const deepValue = a?.b?.c?.d;

// Nullish coalescing: fornisce un default quando il valore è null/undefined
const name = user?.name ?? "Anonimo";
```

`?.` interrompe la valutazione della catena nel momento in cui incontra `null` o `undefined` e restituisce `undefined` invece di lanciare un errore. `??` ti permette poi di sostituire quell'`undefined` con un default sensato — nota che scatta solo su `null`/`undefined`, a differenza di `||`, che scatta anche su `0`, `""` e `false`.

> **Optional chaining non sostituisce la gestione del caso dati mancanti**
>
> `user?.name` produce silenziosamente `undefined` invece di crashare, ma se la tua UI poi
> renderizza quell'`undefined` come testo letterale o lo passa a qualcosa che si aspetta una
> stringa, hai semplicemente scambiato un errore rumoroso con un bug silenzioso. Usa `?.`/`??` per
> prevenire il crash, ma progetta comunque uno stato esplicito "dati non ancora disponibili" per
> tutto ciò che l'utente vedrà davvero.

## "Cannot read properties of undefined" vs "...of null"

Vedrai anche il quasi identico `Cannot read properties of null (reading 'x')`. La distinzione conta in fase di debug: `undefined` di solito significa che una variabile non è mai stata assegnata o che una proprietà non è mai esistita sull'oggetto; `null` di solito significa che qualcosa è stato deliberatamente impostato a "nessun valore" — una query DOM che non ha trovato nulla (`document.querySelector('.missing')` restituisce `null`), o un campo di database esplicitamente azzerato. Entrambi vengono gestiti allo stesso modo da `?.`/`??`, ma sapere quale dei due hai davanti spesso indica da dove iniziare a cercare.

## FAQ

> **TypeScript previene questo errore?**
>
> Con `strictNullChecks` attivo (parte della modalità `strict`), TypeScript segnala la maggior parte
> di questi accessi già in fase di compilazione, invece di lasciarli arrivare al browser come crash
> a runtime — è il modo singolarmente più efficace per intercettare questa classe di bug prima del
> deploy.

> **Posso usare l'optional chaining su una chiamata a funzione?**
>
> Sì — `obj.method?.()` chiama `method` solo se esiste, e restituisce `undefined` invece di lanciare
> "is not a function" se non esiste. Utile per callback opzionali passate come props.

## Conclusione

"Cannot read properties of undefined" non è quasi mai un bug misterioso — è una di tre forme familiari: dati non ancora arrivati, un campo destrutturato che non è mai stato inviato, o un array vuoto usato come se avesse contenuto. Optional chaining e nullish coalescing non risolvono il vuoto logico di fondo, ma trasformano un crash duro in un `undefined` controllabile che puoi verificare esplicitamente — che di solito è esattamente ciò che serve mentre progetti il vero stato "nessun dato".

**Riferimenti**

- [Optional chaining (?.) – MDN](https://developer.mozilla.org/it/docs/Web/JavaScript/Reference/Operators/Optional_chaining)
- [Nullish coalescing operator (??) – MDN](https://developer.mozilla.org/it/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing)
- [strictNullChecks – documentazione TypeScript](https://www.typescriptlang.org/tsconfig/#strictNullChecks)
