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

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

È 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.

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.

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

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:

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

Causa #2: destrutturare un valore che potrebbe essere null

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

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:

// 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.

“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

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

• Nullish coalescing operator (??) – MDN

• strictNullChecks – documentazione TypeScript