TypeError não consegue ler a propriedade indefinida em JavaScript: guia completo de depuração

TypeError: Não é possível ler propriedades de indefinido (lendo ‘x’) é o erro de JavaScript mais comum. Isso significa que você está tentando acessar uma propriedade com um valor que éundefined — como ligaruser.name quandouser is undefined. Aqui estão todas as causas e soluções.

O que o erro realmente significa

// The error occurs here:
const name = user.name;
// TypeError: Cannot read properties of undefined (reading 'name')

// Because:
let user = undefined;
console.log(user);  // undefined
console.log(user.name);  // ❌ TypeError

JavaScript só pode acessar propriedades de objetos. undefined enull não são objetos. Tentar acessar qualquer propriedade neles gera um TypeError.

Causa 1: dados assíncronos ainda não carregados

// 🐛 Bug: accessing data before it's available
const [user, setUser] = useState();  // undefined initially

return 
{user.name}
;  // ❌ renders before fetch completes

// ✅ Fix 1: Default value in useState
const [user, setUser] = useState(null);
return 
{user?.name}
;  // optional chaining

// ✅ Fix 2: Conditional rendering
if (!user) return 
Loading...
;
return 
{user.name}
;

Causa 2: propriedade ou chave com erro ortográfico

const response = {
  data: { users: [...] }
};

// 🐛 Bug: wrong key name
console.log(response.Data.users);  // ❌ 'Data' (capital D) doesn't exist → undefined.users

// ✅ Fix: check the actual shape
console.log(response);  // inspect the full object first
console.log(response.data.users);  // ✅ correct

Causa 3: o elemento da matriz não existe

const users = [];

// 🐛 Bug: accessing index that doesn't exist
console.log(users[0].name);  // ❌ users[0] is undefined

// ✅ Fix: check length first
if (users.length > 0) {
  console.log(users[0].name);
}

// ✅ Fix: optional chaining on array access
console.log(users[0]?.name);  // returns undefined instead of throwing

Causa 4: Função retorna indefinida

// 🐛 Bug: function doesn't explicitly return a value
function getUser(id) {
  if (id === 1) {
    return { name: "Alice" };
  }
  // no return for other ids → returns undefined
}

const user = getUser(2);
console.log(user.name);  // ❌ user is undefined

// ✅ Fix: always return a value or handle the undefined case
function getUser(id) {
  if (id === 1) return { name: "Alice" };
  return null;  // explicit null is better than undefined
}

const user = getUser(2);
if (user) console.log(user.name);

Causa 5: Acesso a objetos aninhados

const config = {
  database: {
    host: "localhost"
  }
};

// 🐛 Bug: accessing deeply nested path where intermediate is missing
console.log(config.cache.ttl);  // ❌ config.cache is undefined

// ✅ Fix 1: Optional chaining (ES2020, supported everywhere in 2026)
console.log(config.cache?.ttl);  // undefined (no error)

// ✅ Fix 2: Nullish coalescing with default value
const ttl = config.cache?.ttl ?? 300;  // returns 300 if undefined/null

// ✅ Fix 3: Destructuring with defaults
const { cache: { ttl = 300 } = {} } = config;

A correção: encadeamento opcional (?.) e coalescência nula (??)

// Optional chaining: access property only if parent is not null/undefined
const name  = user?.name;           // undefined if user is null/undefined
const city  = user?.address?.city;  // safely access nested path
const first = arr?.[0];             // safe array access
const val   = obj?.method?.();      // safe method call

// Nullish coalescing: provide default for null/undefined
const displayName = user?.name ?? "Anonymous";  // "Anonymous" if name is null/undefined

// NOT the same as || (which treats 0, "", false as falsy)
const count = data.count ?? 0;  // 0 if null/undefined, but keeps 0 if data.count IS 0
const count2 = data.count || 0; // returns 0 even if data.count is 0 (wrong!)

Etapas de depuração quando você vê este erro

1. Leia a mensagem de erro na íntegra: “Não é possível ler propriedades de indefinido (lendo ‘nome’)” indica que éname sendo acessado em algo indefinido.
2. Verifique o rastreamento de pilha: O número da linha aponta exatamente onde. Clique nele no DevTools do navegador para acessar o código.
3. Registre o valor pai: console.log(user) logo antes da linha de falha. Veja o que realmente é.
4. Verifique quando os dados estão disponíveis: Esses dados são assíncronos? O componente está sendo renderizado antes da conclusão da busca?
5. Procure onde o valor está definido: Encontre todos os lugaresuser (ou o que quer que seja indefinido) é atribuído. Uma dessas atribuições é produzir indefinido.

Padrões específicos de reação

// Pattern 1: Initial state with loading
function UserCard({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchUser(userId).then(data => {
      setUser(data);
      setLoading(false);
    });
  }, [userId]);

  if (loading) return ;
  if (!user)   return 
User not found
;

  return 
{user.name}
;  // safe — user is guaranteed to exist
}

// Pattern 2: Optional chaining in JSX
function UserCard({ user }) {
  return (
    <div>
      <h1>{user?.name ?? "Unknown"}</h1>
      <p>{user?.email ?? "No email"}</p>
    </div>
  );
}

TypeScript: capture-os em tempo de compilação

// TypeScript with strict null checks
interface User {
  name: string;
  email?: string;  // optional property
}

function greet(user: User | null | undefined) {
  // TypeScript error: 'user' is possibly 'null' or 'undefined'
  console.log(user.name);  // ❌ compile error

  // TypeScript forces you to handle null cases
  console.log(user?.name);  // ✅ safe
}

// Enable strict null checks in tsconfig.json:
// "strictNullChecks": true  (enabled by default with "strict": true)

Perguntas Frequentes

P: Qual é a diferença entre indefinido e nulo?
A: undefined significa que uma variável foi declarada, mas nunca recebeu um valor. null é uma ausência intencional de valor que um desenvolvedor define explicitamente. Ambos lançam TypeError quando você acessa propriedades neles.

P: Devo usar encadeamento opcional em todos os lugares?
R: Use-o onde os valores podem ser genuinamente indefinidos. O uso excessivo (encadeamento de tudo) esconde bugs – você pode preferir um erro explícito quando algo que deveria existir não existe.

P: Por que o TypeScript não evita todos esses erros?
R: O TypeScript captura a maioria deles em tempo de compilação com o modo estrito habilitado. Mas o TypeScript possui saídas de escape (ascasting,!asserções não nulas) que podem ignorar as verificações. Além disso, os dados das APIs sãoany por padrão, a menos que você o valide.

P: Qual é o impacto no desempenho do encadeamento opcional?
R: Insignificante. O encadeamento opcional é compilado para uma verificação nula simples:user === null || user === undefined ? undefined : user.name. Nenhuma preocupação de desempenho.

P: Como posso lidar de forma limpa com dados opcionais profundamente aninhados?
R: Use encadeamento opcional:a?.b?.c?.d. Para transformações de dados complexas, bibliotecas como a do Lodash_.get(obj, 'a.b.c', defaultValue) ou immer pode ajudar. Para respostas de API, use uma biblioteca de validação como Zod para garantir a forma.

Conclusão

TypeError: Não é possível ler propriedades de indefinido é sempre causado pelo acesso a uma propriedade antes de verificar se o valor existe. A solução para 2026 éencadeamento opcional (?.) combinado com coalescência nula (??)para valores padrão, modo estrito TypeScript para segurança em tempo de compilação e padrões de codificação defensivos para dados assíncronos (mostrar estado de carregamento, manipular nulo explicitamente). Depois de internalizar “verificar antes de acessar”, esse erro se torna raro em seu código.